使用Github Pages搭建博客

虽然已经有了BeiYuu的搭建博客教程，一步一步跟着作，我仍是遇到了不少的问题。整理以下：

Github Pages的特色

优势

1. 轻量级的博客系统，没有麻烦的配置
2. 使用标记语言，好比Markdown语法
3. 无需本身搭建服务器
4. 根据Github的限制，对应的每一个站都有空间限制
5. 能够绑定本身的域名

缺点

1. 使用Jekyll模板系统，至关于静态页发布，适合博客，文档介绍等。
2. 动态程序的部分至关局限，好比没有评论，不过还好咱们有解决方案。
3. 基于Git教程，不少东西须要动手，不像Wordpress有强大的后台

学习Git

Git简介

1. Git是目前世界上最早进的分布式版本控制系统（没有之一）。
2. Git有什么特色？简单来讲就是：高端大气上档次。

安装GIt

Windows下要使用不少Linux/Unix的工具时，须要Cygwin这样的模拟环境，Git也同样。Cygwin的安装和配置都比较复杂，就不建议你折腾了。不过，有高人已经把模拟环境和Git都打包好了，名叫msysgit，只须要下载一个单独的exe安装程序，其余什么也不用装，绝对好用。

msysgit是Windows版的Git，从http://msysgit.github.io/下载，而后按默认选项安装便可。
安装完成后，在开始菜单里找到“Git”->“Git Bash”，蹦出一个相似命令行窗口的东西，就说明Git安装成功！

为github添加SSH key

生成SSH key

$ ssh-keygen -t rsa -C "youremail@example.com"

而后一路点击回车便可。若是一切顺利的话，能够在用户主目录里找到.ssh目录，里面有id_rsa和id_rsa.pub两个文件，这两个就是SSH Key的秘钥对，id_rsa是私钥，不能泄露出去，id_rsa.pub是公钥，能够放心地告诉任何人。
查看id_rsa.pub有两种方式:
1.windows7下看生成的文件

C:\Users\username\.ssh\id_rsa.pub

2.经过vim命令查看

vim ~/.ssh/id_rsa.pub

而后将生成的key拷贝到Github Pages中。

测试链接

$ ssh -T git@github.com

若是提示以下内容表示添加SSH key 成功

Hi yourusername! You've successfully authenticated, but GitHub does not provide shell access.

学习Markdown

Markdown语法比较简单，我这里使用的是在线编辑器Cmd Markdown。在这个编辑器中，能够经过ctrl+alt+H方式查看Markdown语法。

学习Jekyll

这里耽误最多时间的就是学习Jekyll了。尤为是搭建本地Jekyll的时候。个人环境是windows 7 64 bit，而Jekyll官网上面并无支持这个版本，因此我遇到了很多问题。

Jekyll（发音/'dʒiːk əl/，"杰克尔"）是一个静态站点生成器，它会根据网页源码生成静态文件。它提供了模板、变量、插件等功能，因此实际上能够用来编写整个网站。
整个思路到这里就很明显了。你先在本地编写符合Jekyll规范的网站源码，而后上传到github，由github生成并托管整个网站。

优势：

1. 免费，无限流量
2. 享受git的版本管理功能，不用担忧文章遗失。
3. 你只要用本身喜欢的编辑器写文章就能够了，其余事情一律不用操心，都由github处理。

缺点：

1. 有必定技术门槛，你必需要懂一点git和网页开发。
2. 它生成的是静态网页，添加动态功能必须使用外部服务，好比评论功能就只能用disqus。
3. 它不适合大型网站，由于没有用到数据库，每运行一次都必须遍历所有的文本文件，网站越大，生成时间越长。　

为什么要使用静态网站生成器？

不一样于 WordPress 这类博客平台（以及其余众多流行的CMS内容管理系统）在服务器端执行PHP等语言的动态框架、访问SQL数据库并动态产生Web页面的工做方式，静态网站生成器的原理十分简单：将全部的页面、布局和帖子集合在一块儿，预先生成静态的站点。对于动态内容并不是必要的站点——例如我的博客，静态网站生成器这样作有几个明显的优点：

1.快速访问和弱服务器需求

静态HTML页面的载入速度理所固然地更快——由于它无需在服务器端执行任何代码。同时，这还大大地减轻了服务器的压力。

2.高安全性

基于与上述相同的理由，静态页面有着与生俱来的安全性。不像WordPress或者其余任何动态的框架，静态站点自己并不存在安全漏洞的问题。

3.版本控制

你无需经过WordPress来维护一整个复杂的数据库——静态站点的内容彻底仅由文件系统中独立的目录和文件构成，这意味着你不但可使用Shell、grep、sed、awk这些传统的Unix工具对它们执行操做和维护，更可使用 Git 这样的分布式版本控制系统来管理它们，而且享受版本控制所带来的一切好处，如同维护任何软件项目的源代码库同样。你甚至能够从新生成之前任意时间点的整个网站！

4.简单部署

一旦静态网站生成之后，任何Web服务器都可以轻易地部署静态站点，而无须在服务器端安装配置其余任何多余的东西。你所须要作的仅仅是经过git、rsync甚至ftp简单地上传文件到你的托管服务器。相比之下，WordPress博客的维护显得复杂得多，你可能须要在你的开发服务器和托管服务器上安装、配置一整套LAMP+WordPress平台，并常常性地升级版本和维护。这是个繁重的技术活。

5.文本编辑器和自由格式书写

也许你不这么认为，可是做为一个hacker而言，在浏览器中一个300x300的文本区里码字写博客并不是一件很酷的事情——若是你使用Jekyll这样的静态网站生成器，你就能够用你喜欢的任何文本编辑器（vi、emacs……），用你习惯的标记语言以书写文本文件的方式来直接写博客文章（就好像你日常写代码同样），避免了使用那些简陋和功能有限的Web界面。

搭建本地Jekyll环境

我本地的操做系统是windows 7 64位系统。早前我没有搭建本地环境，因此每一次修改都须要提交到Github 上面才能查看修改效果，很是不方便。因此搭建了一个本地环境。

官方文档中指出了能够在Linux, Unix, 和 Mac OS X中安装Jekyll。虽然不支持windows，可是在下方给出了在windows中的解决方案。Running Jekyll on windows。

1.下载RubyInstaller。我选择的是Ruby 2.0.0-p451 (x64)

【错误1】按照Ruby时路径错误
在安装Ruby的时候，个人出现了一个安装问题。我安装在了D:\Program Files目录。注意这里有一个空格哟，Ruby安装不成功的。可是我想不明白，明明在C盘下面就一个C:\Program Files的嘛。为何win7安装目录会有一个空格呢？

【解决1】修改路径名
将带空格的路径改成不带空格就好了呗。

2.安装Ruby DEVELOPMENT KIT。我选择的是For use with Ruby 2.0 (x64 – 64bits only)

【错误2】配置Ruby DEVELOPMENT KIT出错。
按照上面给出的windows解决方案中，会执行一下ruby dk.rb init，而后能够在devkit中找到一个config.fml文件。

【解决2】修改config.fml文件
修改文件以下:

# This configuration file contains the absolute path locations of all  
# installed Rubies to be enhanced to work with the DevKit. This config  
# file is generated by the 'ruby dk.rb init' step and may be modified  
# before running the 'ruby dk.rb install' step. To include any installed  
# Rubies that were not automagically discovered, simply add a line below  
# the triple hyphens with the absolute path to the Ruby root directory.  
#  
# Example:  
#  
# ---  
# - C:/ruby19trunk  
# - C:/ruby192dev  
#  
---  
- D:/ProgramFiles/Ruby200-x64

说明：

1. #表示注释。
2. 必定要保留"-"
3. 在下面填写你本地Ruby的安装目录
4. ruby dk.rb init 的时候若是提示"Initialization complete!"。表示成功了。
5. 执行成功后，继续执行ruby dk.rb review和 ruby dk.rb install

3.安装Jekyll

当Ruby环境配置完成后（不提示任何错误），就能够安装Jekyll了。执行gem jekyll install
【错误3】安装Jekyll 时候出错。

ERROR:  Could not find a valid gem 'jekyll' (>= 0) in any repository  
ERROR:  Possible alternatives: jekyll`

【解决3】Github jekyll中有解决方案

$ gem sources --remove http://rubygems.org/
$ gem sources -a http://ruby.taobao.org/
$ gem sources -l
*** CURRENT SOURCES ***
http://ruby.taobao.org    
$ gem install rack

而后继续执行gem install jekyll便可。等待片刻，会提示21 gems installed。jekyll 安装完毕。

---------- 20150316补充 ----------
确保gem sources -l以后列表中只有ruby.taobao.org。详情请看RubyGems 镜像

4.建立blog

在随便一个磁盘下面建立一个文件夹myblog便可

G:\work>jekyll new myblog
G:\work>jekyll serve

【错误4】invalid byte sequence in GBK
注意，我这里是在work目录下启动的jekyll哦。这也是出现问题的一个缘由了。。囧。
错误以下：

Configuration file: none  
        Source: G:/work  
   Destination: G:/work/_site  
  Generating... Error reading file G:/work/web/github-    pages/siberiawolf.gith  
ub.io/_posts/blog/2012-02-22-github-pages.md: invalid byte sequence in GBK  
error: invalid byte sequence in GBK. Use --trace to view backtrace

【解决4】这个问题解决的让我比较纠结。全都记录下来吧。
解决方法1
根据Jekyll在Windows下面中文编码问题解决方案这里的解决方案，我全都找了一遍，可是依然没有解决。
首先在我convertible.rb文件中，根本就没有文章中提到的那段添加utf-8的代码。
最后这个文章中提到的编码格式、换行符、YAML格式，我这里都没有问题。

解决方法2
最后我只是简单的将出现GBK错误的文件删掉了。这里出现错误的缘由是由于在个人G盘下面，存在的一个文件被Jekyll检测到了。而问题的根本缘由是，我启动jekyll serve的时候，是在work目录下进行的，而不是在myblog这个目录下。Jekyll将work目录下的全部文件都遍历了一遍。

【错误5】Forbidden no access permission to /
这个错误是跟上面错误相关联的。
解决方法1
google找到到stackoverflow中的一篇问答，试着修改一下 Pygments.rb。可是我不肯定他的版本是多少。
结果发现个人版本是0.5.4，而后按照里面提供的方法，将0.5.4卸载掉，安装0.5.0,而后从新启动服务，打开浏览器访问，发现，仍是会出现这个Forbidden ..

解决方法2
进入到myblog(我建立的jekyll目录)，在这个目录下试着启动jekyll serve，而后用浏览器访问就不会出现forbidden了。。囧.....
而后【错误4】也就解决了。

【错误6】页面空白
页面虽然能访问了，可是一片空白啊，什么都没有

【解决6】删掉highlight代码
在Jekyll new myblog的时候，在_post目录下生成的文件中，找到以下代码，而后删除掉。

最后成功启动Jekyll 的界面以下：

5.代码高亮

【错误7】Conversion error: There was an error converting..
就是在md文件中存在Ruby代码$ cd ~/.ssh。而这段代码应该是经过高亮的方式显示的。

【解决7】使用Markdown rdiscount
这个博客使用的是Google Code Prettify代码高亮。我本地的是使用方法没有问题，可是为何会不支持代码高亮呢？
对比发现个人_config.yml文件markdown属性不是rdiscount，默认生成的_config.yml文件是redcarpet 。而后我就将这个值修改成rdiscount，可是报错。

ERROR: YOUR SITE COULD NOT BE BUILT:------------------------------------Missing dependency: rdiscount

根据提示，我执行命令$ gem install rdiscount，可是我这里一直安装不上。

偶然间，我修改了一下控制面板中的区域语言中的格式修改成英语（美国），而后在执行$ gem install rdiscount，竟然成功了。

提示gem安装成功。而后代码也就高亮了。并且也不会出现那个Conversion error了。

如下资源解决了我很多困惑：

1. Getting My Site Running With Markdown + Jekyll!
2. Jekyll中使用google-code-prettify高亮代码

6.解决中文编码

上面提到过，出现了GBK问题。并且我也没有找到convertible.rb文件中的那段代码。那么怎么支持中文呢？
实际上最新版本的Jekyll已经解决了这个问题。只是再也不这里处理了。而是在_config.fml文件中配置一下便可。

encoding: utf-8
markdown: rdiscount

学习Jekyll Liquid模板语言

Jekyll使用Liquid模板语言，{{ page.title }}表示文章标题，{{ content }}表示文章内容，更多模板变量请参考官方文档。

须要用到什么语法，直接看文档就好了。

---------- 20150317补充 ----------

依赖包 rdiscount 未找到

Generating... You are missing a library required for Markdown. Please run:
$ [sudo] gem install rdiscount
Conversion error: There was an error converting '_posts/2013-04-22-yizeng-hello-world.md/#excerpt'.

ERROR: YOUR SITE COULD NOT BE BUILT:
   ------------------------------------
   Missing dependency: rdiscount

依赖包 rdiscount 未找到。 此问题最有可能的缘由是，网站使用的是 rdiscount 做为 Markdown 引擎，而不是 Jekyll 默认的引擎，故须要手动自行安装。执行gem install rdiscount

cannot load such file -- hitimes/hitimes (LoadError)

/Library/Ruby/Gems/2.0.0/gems/hitimes-1.2.2/lib/hitimes.rb:37:in `require': cannot load such file -- hitimes/hitimes (LoadError)
from /Library/Ruby/Gems/2.0.0/gems/hitimes-1.2.2/lib/hitimes.rb:37:in `rescue in <top (required)>'
from /Library/Ruby/Gems/2.0.0/gems/hitimes-1.2.2/lib/hitimes.rb:32:in `<top (required)>'
from /Library/Ruby/Gems/2.0.0/gems/timers-4.0.1/lib/timers/group.rb:4:in `require'
from /Library/Ruby/Gems/2.0.0/gems/timers-4.0.1/lib/timers/group.rb:4:in `<top (required)>'
from /Library/Ruby/Gems/2.0.0/gems/timers-4.0.1/lib/timers.rb:4:in `require'
from /Library/Ruby/Gems/2.0.0/gems/timers-4.0.1/lib/timers.rb:4:in `<top (required)>'
from /Library/Ruby/Gems/2.0.0/gems/celluloid-0.16.0/lib/celluloid/receivers.rb:3:in `require'
from /Library/Ruby/Gems/2.0.0/gems/celluloid-0.16.0/lib/celluloid/receivers.rb:3:in `<top (required)>'
from /Library/Ruby/Gems/2.0.0/gems/celluloid-0.16.0/lib/celluloid.rb:475:in `require'
from /Library/Ruby/Gems/2.0.0/gems/celluloid-0.16.0/lib/celluloid.rb:475:in `<top (required)>'
from /Library/Ruby/Gems/2.0.0/gems/listen-2.7.11/lib/listen.rb:1:in `require'
from /Library/Ruby/Gems/2.0.0/gems/listen-2.7.11/lib/listen.rb:1:in `<top (required)>'
from /Library/Ruby/Gems/2.0.0/gems/jekyll-watch-1.1.2/lib/jekyll/watcher.rb:25:in `require'
from /Library/Ruby/Gems/2.0.0/gems/jekyll-watch-1.1.2/lib/jekyll/watcher.rb:25:in `build_listener'
from /Library/Ruby/Gems/2.0.0/gems/jekyll-watch-1.1.2/lib/jekyll/watcher.rb:6:in `watch'
from /Library/Ruby/Gems/2.0.0/gems/jekyll-2.5.1/lib/jekyll/commands/build.rb:68:in `watch'
from /Library/Ruby/Gems/2.0.0/gems/jekyll-2.5.1/lib/jekyll/commands/build.rb:38:in `process'
from /Library/Ruby/Gems/2.0.0/gems/jekyll-2.5.1/lib/jekyll/commands/serve.rb:26:in `block (2 levels) in init_with_program'
from /Library/Ruby/Gems/2.0.0/gems/mercenary-0.3.4/lib/mercenary/command.rb:220:in `call'
from /Library/Ruby/Gems/2.0.0/gems/mercenary-0.3.4/lib/mercenary/command.rb:220:in `block in execute'
from /Library/Ruby/Gems/2.0.0/gems/mercenary-0.3.4/lib/mercenary/command.rb:220:in `each'
from /Library/Ruby/Gems/2.0.0/gems/mercenary-0.3.4/lib/mercenary/command.rb:220:in `execute'
from /Library/Ruby/Gems/2.0.0/gems/mercenary-0.3.4/lib/mercenary/program.rb:35:in `go'
from /Library/Ruby/Gems/2.0.0/gems/mercenary-0.3.4/lib/mercenary.rb:22:in `program'
from /Library/Ruby/Gems/2.0.0/gems/jekyll-2.5.1/bin/jekyll:20:in `<top (required)>'
from /usr/local/bin/jekyll:23:in `load'
from /usr/local/bin/jekyll:23:in `<main>'

hitimes版本冲突了。个人解决办法是安装hitimes-1.2.1，执行命令gem 'hitimes', '~> 1.2.1'，而后把Ruby安装目录下D:\ProgramFiles\Ruby22\lib\ruby\gems\2.2.0\gems多余的hitimes版本删除掉

总结

记录我本身搭建这个博客的过程、遇到的问题。