GitHub雖然不是一個傳統的博客託管站點，但已成爲程序員寫博客的最愛，下面介紹幾種在github上寫博客的方法.
1. Github pages
github提供了pages功能, 分別是user pages和project pages, 區別如下:
| User Page | Project Page | |
|---|---|---|
| 是否多個 | 一個帳號只有一個 | 可以有多個, 每個repo都可以有對應的Project page |
| repo and branch | repo名必須爲<username>.github.io, 頁面在master上 |
repo名隨意, 頁面必須在分支gh-pages下 |
| URL | http(s)://<username>.github.io |
http(s)://<username>.github.io/<projectname> |
舉例 - w3c:
W3C是一個使用github pages的一個很好的例子, w3c是github帳號名, 在user pages上定義瞭如何定義w3c spec, 即在repo "w3c.github.io" (對應的repo地址爲 https://github.com/w3c/w3c.github.io ), 我們可以使用URL http://w3c.github.io 訪問對應頁面, 每一個spec都對應了一個project repo, 譬如webrtc, 文檔定義在repo "webrtc-pc"的分支"gh-pages"下面, 對應的URL爲 http://w3c.github.io/webrtc-pc
優點:
- 可以使用任意模版
- 是最正統的在github上寫博客的方法
缺點:
- 需要自己定義模版 (也可以找別人現成的模版)
- 不能在線寫博客, 需要在本地編寫博客文件, 然後使用git命令提交到github
- 需要理解github pages, 需要懂git命令, 有一些門檻
總結:
- 這個方式適合對博客模版有要求, 瞭解git和github pages的人
- 因爲有一點門檻, 適合愛折騰的程序員, 不適合普通人
2. 直接提交靜態文件到github pages (Hexo等)
Github Pages其實等於jekyll engine + static web server, 方法1其實是利用jekyll搭建blog, 這兩個功能都用到了.
我們也可以不使用jekyll engine, 只利用static web server這個功能, 也就是說, 直接上傳靜態站點文件html/css/javascript/image等等, 讓Github Pages幫我們host這些靜態頁面.
Hexo + Github pages搭建blog其實就是隻利用了github pages的static web server功能, hexo基於node.js, hexo在本機將用戶的blog翻譯成靜態頁面, 然後將這些靜態頁面上傳到github上, 由github pages的static web server部署這些靜態頁面.
hexo與jekyll的主要區別是:
-
md到html的轉換時機不同,hexo在本機完成, jekyll是由github pages完成 - 提交到github庫裏的文件不同, hexo是提交轉換後的靜態頁面, jekyll是提交轉換前的md文件
我們可以使用hexo在本機寫博客, 然後上傳靜態文件到github, 我們也可以使用其他模版引擎在本機寫博客, 其實方法1裏, 我們如果利用本機jekyll編譯出靜態文件, 然後只提交這些靜態文件, 這樣的做法和Hexo是一樣的, 或者, 你也可以使用任何一種模版引擎 ( https://github.com/coffee-js/languages/wiki/static-blog-tools )來生成靜態博客站點, 當然, 你也可以直接寫html.
優點:
- 可以使用任意模版技術, 方法1其實是jekyll模版技術
- 可以使用任意模版
- 仍然是正統的在github上寫博客的方法
缺點:
- 需要找到適合自己的模版技術, hexo是比較流行的一種
- 需要自己定義模版 (也可以找別人現成的模版)
- 需要在本地編寫博客文件, 然後使用git命令提交到github
- 需要理解github pages, 需要懂git命令, 需要懂模版技術, 有一些門檻
總結:
- 這個方式適合對博客模版有要求, 瞭解模版技術, 瞭解git和github pages的人
- 有一點門檻, 適合愛折騰的程序員, 不適合普通人
3. 利用github issue寫博客
利用github issues寫博客也是一種做法. 我的博客: https://github.com/rainzhaojy/blogs/issues
優點:
- 簡單方便
- 可以在線寫, 可以預覽, 可以評論, 可以加tag
缺點:
- 無法定製模版
總結:
- 如果你對github issues的格式能夠接受, 那麼這是最適合的方式
- 基本沒有門檻, 適合絕大多數人, 推薦
4. 利用github wiki寫博客
github wiki當然也可以寫博客, github上每一個projec都有一個對應的wiki, 你可以在這裏寫博客, 譬如 https://github.com/coffee-js/languages/wiki
優點:
- 就是一個wiki系統，可以靈活的創建wiki page並相互link，也可以自定義右邊的sidebar
缺點:
- 相比github issues，沒有comments功能
5. 直接在repo裏提交markdown文件
github建議每個項目都提供一個README.md文件, 在網頁上瀏覽項目或子目錄時, github會自動顯示當前目錄裏的README.md文件, 利用這一功能, 也有人直接提交markdown文件, 譬如 https://github.com/kilimchoi/engineering-blogs, 這樣也是一種方法, 只是打開你的blog時上面會先看到file list.
這樣的做法其實就是把博客的md文件當成源代碼一樣提交到github裏.
優點:
- 相比前面幾種, 好像沒什麼獨有的優點
缺點:
- 會看到文件列表, 格式比issues/wiki難看
- 需要懂git命令, 有一些門檻
總結:
- 既沒有方法1, 2能夠定製模版這樣的優點, 又沒有方法3, 4裏可以在線編輯的優點, 因此不推薦這個方法
6. 項目文檔的好選擇
最近在爲公司項目文檔選型的時候發現一個不錯的項目https://docusaurus.io/, 這是Facebook的開源項目，基於Nodejs，使用markdown，非常適合用於寫項目文檔，也可用於個人知識整理，相當於是wiki+blog系統，非常方便，樣式也不錯，和GA、搜索等也都集成的不錯，也可以和GitHub Pages集成。拍樂雲的項目文檔就使用了這個，參考這裏：https://developer.pano.video, Enjoy！