使用Github Pages搭建博客 - 快车库

虽然已经有了BeiYuu的搭建博客教程，一步一步跟着做，我还是遇到了很多的问题。整理如下：

Github Pages的特点

优点

轻量级的博客系统，没有麻烦的配置
使用标记语言，比如Markdown语法
无需自己搭建服务器
根据Github的限制，对应的每个站都有空间限制
可以绑定自己的域名

缺点

使用Jekyll模板系统，相当于静态页发布，适合博客，文档介绍等。
动态程序的部分相当局限，比如没有评论，不过还好我们有解决方案。
基于Git教程，很多东西需要动手，不像Wordpress有强大的后台

学习Git

Git简介

Git是目前世界上最先进的分布式版本控制系统（没有之一）。
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生成并托管整个网站。

优点：

免费，无限流量
享受git的版本管理功能，不用担心文章遗失。
你只要用自己喜欢的编辑器写文章就可以了，其他事情一概不用操心，都由github处理。

缺点：

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

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

不同于 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

说明：

#表示注释。
一定要保留"-"
在下面填写你本地Ruby的安装目录
ruby dk.rb init 的时候如果提示"Initialization complete!"。表示成功了。
执行成功后，继续执行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了。

以下资源解决了我不少困惑：

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版本删除掉

总结

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