使用 Github Pages 發佈你的項目文檔

導讀	你可能比較熟悉如何用 Github Pages 來分享你的工做，又或許你看過一堂教你創建你的第一個 Github Pages 網站的教程。近期 Github Pages 的改進使得從不一樣的數據源來發布您的網站更加的方便，其中的來源之一就是你的倉庫的 /docs 目錄。

文檔的質量是一個軟件項目健康發展的標誌。對於開源項目來講，維護一個可靠而不出錯的知識庫、詳細說明全部的細節是相當重要的。精心策劃的文檔可讓增長項目的親切感，提供一步步的指導並促進各類方式的合做能夠推進開源軟件開發的協做進程。

在 Web 上託管你的文檔是一個消耗時間的挑戰，並且對於它的發佈和維護也沒有省事的辦法，然而這是並不是不可避免的。面對多種不一樣的發佈工具，又是 FTP 服務器，又是數據庫，文件以各類不一樣的方式存放在不一樣的位置下，而這些都須要你手動來調整。須要說明的是，傳統的 Web 發佈方式提供了無與倫比的靈活性和性能，可是在許多狀況下，這是以犧牲簡單易用爲代價的。

看成爲文檔使用時，麻煩更少的方式顯然更容易去維護。

GitHub Pages 能夠以指定的方式爲你的項目建立網站，這使得它自然地適合發佈和維護文檔。由於 Github Pages 支持 Jekyll，因此你可使用純文本或 Markdown 來書寫你的文檔，從而下降你維護的成本、減小維護時的障礙。Jekyll 還支持許多有用的工具好比變量、模板、以及自動代碼高亮等等，它會給你更多的靈活性而不會增長複雜性，這些你在一些笨重的平臺是見不到的。

最重要的是，在 Github 上使用 GitHub Pages 意味着你的文檔和代碼可使用諸如 Issues 和 Pull Requests 來確保它獲得應有的高水平維護，並且由於 GitHub Pages 容許您發佈代碼庫主分支上的 /docs 目錄，這樣您就能夠在同一分支同時維護你的代碼庫及其文檔。

如今開始！

發佈你的第一個文檔頁面只須要短短几分鐘。

1. 在你的倉庫的主分支裏建立一個 /docs/index.md 文件。
2. 把你的內容以 Jekyll 格式添加進去，並提交你的修改。
   
3. 查看你的倉庫的設置分支而後選擇主分支 /docs 目錄，將其設置爲 GitHub Pages 的源 ，點擊保存，你就搞定了。

GitHub Pages 將會從你的 /docs 目錄中讀取內容，轉換 index.md 爲 HTML。而後把它發佈到你的 GitHub Pages 的 URL 上。

這樣將會建立並輸出一個最基礎的 HTML ，並且你可使用 Jekyll 的自定義模板、CSS 和其餘特性。若是想要看全部的可能，你能夠看看 GitHub Pages Showcase。