使用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版本刪除掉

總結

記錄我本身搭建這個博客的過程、遇到的問題。