利用 Gitbook 生成文件中心站點

經過乙個多月，bugtags 最近上線了自己的文件站點：docs.bugtags.com，在這裡你可以找到 bugtags 整合、使用相關的絕大部分問題。

比如：該產品文件是使用富文字形式編輯和儲存在資料庫的；而我們自己都非常喜歡於用 markdown 格式編寫文件；而資料庫儲存也注定無法使用 git 來進行文件的版本管理和控制；

幫助中心頁面的樣式只有預設的幾套，儘管提供了模板設計功能，但其實也非常雞肋，完全無法滿足我們的自定製需求。基於此我們嘗試尋找其他的方案解決這個問題。

我們首先想明白我們需要什麼樣的文件管理系統；

1、使用 markdown 來撰寫文件，所謂「無 markdown，不文件」；我們工程師都習慣於使用 markdown 來撰寫文件，甚至我司唯一不會技術的美女靜靜都表示：「文件怎麼可以不是 markdown 的呢！」就剛剛催稿時她還說：「必須是 markdown 啊，不然我不收的」。

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

在一系列嘗試之後，我們開始採用 gitbook 並對他進行改寫，來生成起自己的文件中心站點。

gitbook 是乙個電子書製作程式；它把組織起來的 markdown 檔案按照層次生成電子書；這個電子書的格式可以是epub、mobi、pdf，甚至還可以是乙個**；

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

使用gitbook init命令，會根據檔案summary.md中的內容來生成書籍目錄結構；

使用gitbook build把書籍生成你需要的格式。

然後所有的書籍配置都可以通過根目錄下的book.json檔案來定義。

關於 gitbook 較詳細的使用方法，可以參考 gitbook 簡明教程，這個**本身也是由 gitbook 來生成的。

gitbook 與我們的需要匹配較強，有以下幾點：

開源。作為乙個初創小企業，我們的很多專案受益於開源產品。有很多第三方的外掛程式來推動這個產品發展；

markdown 格式撰寫文件；

目錄結構清晰；我們可以把所有的 markdown 文件按照不同的主題歸集到不同的目錄層次下；

生成的網頁純靜態。gitbook 是可以把所有的 markdown 文件生成靜態的 html 頁面；

由於所有的內容都是 markdown 檔案，所以就可以使用 git 來進行版本管理和控制了；

在伺服器上安裝 gitbook 後，定製乙個git hook指令碼，就可以在每次文件更新提交後自動生成**；

gitbook 本身的理念是把 markdown 檔案組織成一本書的概念；這與我們需要做的乙個**還是有些不太一樣的；所以會有很多需要改變的地方。

你看我們的**跟任意乙個 gitbook 預設生成的站點對比，比如 gitbook 官方的幫助文件站點 ,會發現很多不一樣；具體來說，我們修改下面這些東西：

目錄生成邏輯

我們在gitbook 的模板中新增了頁頭、頁尾。頁面目錄的樣式也不一樣：這個可不只是展現形式不一樣了。細心翻閱會發現，在我們的文件**中，有一些文件並沒有出現在目錄裡。比如有很多繁瑣的常見問題；如果每一篇都要放到目錄裡，目錄會變得很冗長。這些就得改變 gitbook 預設的目錄選單的生成邏輯了。

我們是這麼做的：在summary.md檔案（這個檔案中的內容來定義目錄結構）中專門定義乙個層次，這個層次名稱叫做hide-docs，類似於這個樣子：

123

- [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方法，我們的**是這樣：

123

4567

891011

1213

if( !this.replacedsummary);
if( that.book.summary && that.book.summary.chapters && that.book.summary.chapters.length )
this.replacedsummary.chapters.push(cur);}}
}

然後將該方法返回物件的summary屬性指定為我們篩選過的replacedsummary變數。這樣再執行gitbook build，就會發現所有的 markdown 都被生成了 html，然而生成的 html 頁面中的目錄不包含這些我們需要隱藏的文件。

外掛程式禁用

gitbook 預設啟用了搜尋，字型調整等 5 個外掛程式，但是我們是不需要這些；所以需要通過在book.json中指定plugins屬性為如下：

123

用減號表示不啟用這些外掛程式（這種配置方法官方幫助文件居然沒提）。

搜尋接下來重點的部分就是搜尋了，因為 gitbook 官方的搜尋根本不支援中文搜尋，所以我們禁用了它，儘管有開源的支援中文的搜尋外掛程式，但是搜尋結果的展示都是非常不直觀；這些都需要從模板以及搜尋引擎兩方面來改進。

文件搜尋我們最後採用的是強大 elasticsearch 來提供全文搜尋服務，並且配合修改模板來顯示搜尋結果。關於 elasticsearch，這是個更複雜的話題了；這裡不單說，有興趣的朋友可以搜尋相關教程。

模板由於 gitbook 是把 markdown 組織成一本書的概念；對一本書來說，除了封面就是目錄以及目錄組織起來的正文。

而我們需要的是乙個文件**，不僅需要文件內容頁面，還需要其他的頁面，比如首頁，搜尋頁面， 404 頁面，可能還需要其他的頁面。這時候我不禁非常懷念jekyll這個靜態部落格生成工具，它會把根目錄所有的 html 檔案找到其對應模板巢狀生成 html 頁面。

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

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

最後，我們採用了 gitbook 符合我們需求的部分，把不適應的上面幾點想方設法解決了之後，就形成了我們現在的文件中心站點。

利用 Gitbook 生成文件中心站點

利用 Gitbook 生成文件中心站點

如何利用apidoc自動生成文件

beego api自動生成文件

利用 Gitbook 生成文件中心站點

利用 Gitbook 生成文件中心站點

如何利用apidoc自動生成文件

beego api自動生成文件

相關推薦