Gitbook 的安裝與測試

Gitbook 是一種文件產生的套件軟體，提供使用者可以利用簡單的 Markdown 語法來撰寫文件，再使用 gitbook 的工具轉成書本的形式。最大的好處在於： 使用的是 Markdown 語法，讓一般的使用者可以很容易、輕鬆的撰寫文件，相較於其他的文件產生的套件，例如：Sphinx[1], Docbook, TeX/LaTeX, etc ...入門的門檻已經簡單太多、太多了。命名為 Gitbook，意味著它結合 git 的功能，把文件送到 gitbook 網站，讓世界所有人都可以看到你/妳的作品。除此之外，系統上也有定價的機制，讓瀏覽者可以付費觀看。

Gitbook 是使用雲端來儲存世界上所有使用者撰寫的書籍，網路上也有其相同雲端服務的系統，如：Read The Docs，只要到網路上免費申請帳密，就可以在線上編輯、發布自己所寫得書籍，不需要再特別安裝任何軟體。若要離線編輯 gitbook 書籍，需要安裝它提供的 gitbook Toolchain 軟體。這個工具軟體是使用 Javascript 所撰寫的程式，需要安裝 node.js 引擎，配合 npm 來安裝。在不同平台的安裝與設定上略有差異，以下是在 Windows 系統安裝與測試的過程：

1.  首先安裝 node.js
2. 更新 npm 套件： npm update
3. 安裝 git 軟體： npm install git // 若安裝 STL's MinGW 則不需要再安裝 git
4. 使用 npm 安裝 gitbook 工具程式： npm install -g gitbook-cli

完成安裝程序，就可以開始使用 gitbook 來產生書籍的文件。在使用這個工具之前，先說明這個套件的指令：

1. 輸入 gitbook 出現 gitbook help 文件
2. 安裝完成後，預設的 gitbook版本是 2.1.0 版，可以下指令來檢查：gitbook versions
3. 檢查有幾種版本可以使用： gitbook versions:available
4. 安裝 2.2.0 版： gitbook versions:install 2.2.0
5. 移除 2.1.0 版：gitbook versions:uninstall 2.1.0
6. 檢查輸出的版本： gitbook -V
7. 產生 Webstie 的 HTML 格式： gitbook build
8. 產生其他格式： gitbook pdf; gitbook epub; gitbook mobi

依照測試的結果，在產生其他格式時，會有錯誤訊息，雖然網路上有人建議再安裝 gitbook-pdf，但是，在 GitHub 的gitbook-pdf 專案網站中指出，gitbook 0.4.8 版以後就不需要再安裝 gitbook-pdf 了，這個問題目前暫時無法解決，等以後在處理。

這裡將以一個範例來說明產生文件的過程，範例整個 gitbook目錄結構如下圖：

目錄結構中，只要的有根目錄(pythonTutorial)、zh-tw 目錄、book.json、LANGS.md，在 zh-tw 目錄中有 ch1目錄, ch2目錄, 以及 README.md,  SUMMARY.md 檔，這些檔案的說明如下：

• book.json： gitbook 的設定檔，可以設定使用哪一個版本來產生 gitbook文件，及各種 plugin
• LANGS.md：設定產生多國語言的版本結構，範例的 LANGS.md的內容是：* [繁體中文版](zh-tw/)
• zh-tw/SUMMARY.md： 設定文件章、節的結構。
• 各目錄中的 README.md：整個章、節文件的簡介內容

在 book.json 中有 plugin katex 套件（比 mathjax 快），需要安裝 katex 套件，可以按照下面的指令來安裝：gitbook install

這樣是安裝在 local 目錄中，若使用 npm install -g katex 方式安裝到 global 區，gitbook-cli 需要特別的設定，使它可以連結到對應的程式，目前 gitbook-cli 正在發展階段，或許等以後穩定版就會支援這種 global 安裝方式。

[1] Sphinx is Python document generator, more information refer to Sphinx website.
[2] Gitbook Help 文件：http://help.gitbook.com/index.html