利用 Gitbook 生成文檔中心站點

通過一個多月，Bugtags 最近上線了本身的文檔站點：docs.bugtags.com，在這裏你能夠找到 Bugtags 集成、使用相關的絕大部分問題。

在這以前咱們使用的是第三方提供的幫助中心產品服務，在他們網站後臺上面編輯文檔內容，創建本身的文檔體系的；可是用久了發現仍是用不少不爽的地方，起碼是不符合咱們的習慣；

好比：該產品文檔是使用富文本形式編輯和存儲在數據庫的；而咱們本身都很是喜歡於用 Markdown 格式編寫文檔；而數據庫保存也註定沒法使用 git 來進行文檔的版本管理和控制；
幫助中心頁面的樣式只有默認的幾套，儘管提供了模板設計功能，但其實也很是雞肋，徹底沒法知足咱們的自定製需求。基於此咱們嘗試尋找其餘的方案解決這個問題。

咱們的需求

咱們首先想明白咱們須要什麼樣的文檔管理系統；

一、 使用 Markdown 來撰寫文檔，所謂「無 Markdown，不文檔」；咱們工程師都習慣於使用 Markdown 來撰寫文檔，甚至我司惟一不會技術的美女靜靜都表示：「文檔怎麼能夠不是 Markdown 的呢！」就剛剛催稿時她還說：「必須是 Markdown 啊，否則我不收的」。

二、 生成的網站純靜態，這樣纔會速度快。在起初咱們也想過兩種方案，一是把 Markdown 文件下載到前端，在前端渲染成 HTML；另外一種方案是在後端把全部 Markdown 生成 HTML，前端瀏覽時直接加載 HTML。通過考慮，仍是得采起後一種。若是前一種，讓每個終端用戶都要耗費資源來渲染 Markdown，實在浪費；並且速度沒法保障。然後一種思路就很清晰了：首先寫Markdown文檔，文檔寫完後所有生成靜態網站，這樣終端用戶訪問的所有都是靜態的 HTML 頁面了。

三、 git 管理。這個應該無需多言了吧。文檔的更新升級，必需要有一個強大的版本管理系統，這個非 git 莫屬了。

在一系列嘗試以後，咱們開始採用 Gitbook 並對他進行改寫，來生成起本身的文檔中心站點。

Gitbook 簡介

Gitbook 是一個電子書製做程序；它把組織起來的 Markdown 文件按照層次生成電子書；這個電子書的格式能夠是 epub、mobi、pdf，甚至還能夠是一個網站；

它的使用也是很是簡單，基本上只有兩步：

1. 使用gitbook init命令，會根據文件SUMMARY.md中的內容來生成書籍目錄結構；

2. 使用gitbook build把書籍生成你須要的格式。

而後全部的書籍配置均可以經過根目錄下的 book.json 文件來定義。
關於 Gitbook 較詳細的使用方法，能夠參考 Gitbook 簡明教程，這個網站自己也是由 Gitbook 來生成的。

採用 Gitbook 的緣由

Gitbook 與咱們的須要匹配較強，有如下幾點：

1. 開源。做爲一個初創小企業，咱們的不少項目受益於開源產品。有不少第三方的插件來推進這個產品發展；

2. Markdown 格式撰寫文檔；

3. 目錄結構清晰；咱們能夠把全部的 Markdown 文檔按照不一樣的主題歸集到不一樣的目錄層次下；

4. 生成的網頁純靜態。Gitbook 是能夠把全部的 Markdown 文檔生成靜態的 HTML 頁面；

5. 因爲全部的內容都是 Markdown 文件，因此就可使用 git 來進行版本管理和控制了；

6. 在服務器上安裝 Gitbook 後，定製一個 git hook 腳本，就能夠在每次文檔更新提交後自動生成網站；

Gitbook 不適應咱們需求的地方

Gitbook 自己的理念是把 Markdown 文件組織成一本書的概念；這與咱們須要作的一個網站仍是有些不太同樣的；因此會有不少須要改變的地方。

你看咱們的網站跟任意一個 Gitbook 默認生成的站點對比，好比 Gitbook 官方的幫助文檔站點 ,會發現不少不同；具體來講，咱們修改下面這些東西：

• 目錄生成邏輯；
• 插件使用；
• 搜索；
• 模板樣式。

目錄生成邏輯

咱們在Gitbook 的模板中添加了頁頭、頁腳。頁面目錄的樣式也不同：這個可不僅是展示形式不同了。細心翻閱會發現，在咱們的文檔網站中，有一些文檔並無出如今目錄裏。好比有不少繁瑣的常見問題；若是每一篇都要放到目錄裏，目錄會變得很冗長。這些就得改變 Gitbook 默認的目錄菜單的生成邏輯了。

咱們是這麼作的：在 SUMMARY.md 文件（這個文件中的內容來定義目錄結構）中專門定義一個層次，這個層次名稱叫作 hide-docs，相似於這個樣子：

1 2 3 4 5

- [hide-docs]() - [集成 iOS SDK 看不到懸浮球？](faq/ios/icon-not-found.md) - [用 CocoaPods 集成沒法獲取最新版的 SDK？](faq/ios/cocoapods-sdk-update.md) - [手動集成 SDK 添加 -ObjC 致使編譯出錯？](faq/ios/integrate-manual-build-error.md) - [集成 SDK 後，編譯產生了不少警告？](faq/ios/integrate-build-warning.md)

這個層級下的全部文檔都是不須要出如今目錄下的！然而，Gitbook 照樣會讀取這個層次下的文檔，因此咱們要在生成目錄的邏輯中，稍微改寫：判斷若是是 hide-docs 這個層級下的文檔，就不生成目錄。
這個就得改寫 Gitbook 程序中的 website.js 文件中的 _writeTemplate 方法，咱們的代碼是這樣：

1 2 3 4 5 6 7 8 9 10 11 12 13

if( !this.replacedSummary){ this.replacedSummary = {chapters:[]}; if( that.book.summary && that.book.summary.chapters && that.book.summary.chapters.length ){ var chapters = that.book.summary.chapters; for(var i =0; i < chapters.length;i++){ var cur = chapters[i]; if(/hide-docs/.test(cur.title)){ continue; } this.replacedSummary.chapters.push(cur); } } }

而後將該方法返回對象的 summary 屬性指定爲咱們篩選過的 replacedSummary 變量。這樣再運行gitbook build，就會發現全部的 Markdown 都被生成了 HTML，然而生成的 HTML 頁面中的目錄不包含這些咱們須要隱藏的文檔。

插件禁用

Gitbook 默認啓用了搜索，字體調整等 5 個插件，可是咱們是不須要這些；因此須要經過在 book.json 中指定 plugins 屬性爲以下：

1 2 3

{ "plugins":["-sharing","-livereload","-search","-fontsettings"] }

用減號表示不啓用這些插件（這種配置方法官方幫助文檔竟然沒提）。

搜索

接下來重點的部分就是搜索了，由於 Gitbook 官方的搜索根本不支持中文搜索，因此咱們禁用了它，儘管有開源的支持中文的搜索插件，可是搜索結果的展現都是很是不直觀；這些都須要從模板以及搜索引擎兩方面來改進。

文檔搜索咱們最後採用的是強大 elasticsearch 來提供全文搜索服務，而且配合修改模板來顯示搜索結果。關於 elasticsearch，這是個更復雜的話題了；這裏不單說，有興趣的朋友能夠搜索相關教程。

模板

因爲 Gitbook 是把 Markdown 組織成一本書的概念；對一本書來講，除了封面就是目錄以及目錄組織起來的正文。

而咱們須要的是一個文檔網站，不只須要文檔內容頁面，還須要其餘的頁面， 好比首頁，搜索頁面， 404 頁面，可能還須要其餘的頁面。這時候我不由很是懷念 jekyll 這個靜態博客生成工具，它會把根目錄全部的 HTML 文件找到其對應模板嵌套生成 HTML 頁面。

然而 jekyll（以及我另外嘗試過的 hexo）的缺陷是組織 Markdown 文檔的方式都比較扁平；是經過在每個 Markdown 文檔的首部定義目錄、標籤來定義其邏輯層次，而其生成的物理層次則是經過文件名中的日期來定義的。這是個最大缺陷。

目前我是用了比較野蠻的方式來解決這個問題：

• 首頁：Gitbook 支持多語言，而且若是定義了多語言會有一個模板頁面來生成一個首頁，來選擇語言入口；因此我就把這個本應做爲語言選擇入口的頁面當成咱們的首頁；恩，就是你如今進去看到的那個頁面。
• 404 頁面：本身寫了一個 404，在每次從新生成網站的時候單獨把這個文件拷到根目錄下；感受很傻呢……
• 搜索頁面：每個內容頁均可以是搜索頁；由於我是把搜索結果顯示在當前頁面的內容區域；這樣就能夠局部刷新來展現頁面結果；而不須要單獨作一個模板頁面了。

成果

最後，咱們採用了 Gitbook 符合咱們需求的部分，把不適應的上面幾點千方百計解決了以後，就造成了咱們如今的文檔中心站點。

平時發佈也是很是方便；直接編寫 Markdown 文件，寫完提交到服務器。在服務器端設置了 git hook 鉤子，每次有文檔更新時，都會自動從新生成靜態網站，從新生成搜索索引。你有什麼關於 Bugtags 使用方面的問題，均可以先去這裏查閱一下，歡迎訪問哦。