經過乙個多月，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，類似於這個樣子：
- [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)
hide-docs這個層級下的文件，就不生成目錄。
這個就得改寫 gitbook 程式中的website.js檔案中的_writetemplate方法，我們的**是這樣：
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屬性為如下：
搜尋接下來重點的部分就是搜尋了，因為 gitbook 官方的搜尋根本不支援中文搜尋，所以我們禁用了它，儘管有開源的支援中文的搜尋外掛程式，但是搜尋結果的展示都是非常不直觀；這些都需要從模板以及搜尋引擎兩方面來改進。
文件搜尋我們最後採用的是強大 elasticsearch 來提供全文搜尋服務，並且配合修改模板來顯示搜尋結果。關於 elasticsearch，這是個更複雜的話題了；這裡不單說，有興趣的朋友可以搜尋相關教程。
模板由於 gitbook 是把 markdown 組織成一本書的概念；對一本書來說，除了封面就是目錄以及目錄組織起來的正文。
而我們需要的是乙個文件**，不僅需要文件內容頁面，還需要其他的頁面， 比如首頁，搜尋頁面， 404 頁面，可能還需要其他的頁面。這時候我不禁非常懷念jekyll這個靜態部落格生成工具，它會把根目錄所有的 html 檔案找到其對應模板巢狀生成 html 頁面。
然而jekyll（以及我另外嘗試過的hexo）的缺陷是組織 markdown 文件的方式都比較扁平；是通過在每乙個 markdown 文件的首部定義目錄、標籤來定義其邏輯層次，而其生成的物理層次則是通過檔名中的日期來定義的。這是個最大缺陷。
目前我是用了比較野蠻的方式來解決這個問題：
最後，我們採用了 gitbook 符合我們需求的部分，把不適應的上面幾點想方設法解決了之後，就形成了我們現在的文件中心站點。
利用 Gitbook 生成文件中心站點
經過乙個多月，bugtags 最近上線了自己的文件站點 docs.bugtags.com，在這裡你可以找到 bugtags 整合 使用相關的絕大部分問題。比如 該產品文件是使用富文字形式編輯和儲存在資料庫的 而我們自己都非常喜歡於用 markdown 格式編寫文件 而資料庫儲存也注定無法使用 git...
如何利用apidoc自動生成文件
參考如下 1.2.3.4.5.6.7.簡單的配置如下 django 1.安裝apidoc,寫道 npm install apidoc g 2.按apidoc語法寫好文件，參考5是一篇very good的語法規範 3.生成apidoc文件，我這裡是放在專案根目錄下的static資料夾的apidoc目錄...
beego api自動生成文件
必須設定在 routers router.go 中，檔案的注釋，最頂部 apiversion 1.0.0 title mobile api description mobile has every tool to get any job done,so codename for the new mo...