Gitbook使用入門

不像Readthedocs那麼複雜，Gitbook所需的文件和設置極其少，並且原生支持Markdown和Github倉庫自動同步。

通常本地無需安裝，只要在Github中存入相應的Markdown文件就能自動生成了。
不過爲了隨時測試和預覽，有必要在本地也弄一套。

參考：GitBook 簡明教程

安裝(不要安裝舊版的gitbook，而應該是gitbook-cli)：

$ sudo npm install gitbook-cli -g

常見安裝問題：

#若是提示`npm`版本太低，則升級npm：
$ npm i npm@latest -g

#若是提示網絡問題，則用-d參數
$ npm install gitbook -g -d

#若是網絡仍是有問題，則用代理聯網
$ npm config set proxy http://127.0.0.1:1080
$ npm config set https-proxy http://127.0.0.1:1080

gitbook程序和npm的問題太多，我在Mac本機、Ubuntu國外服務器上測試都裝很差。因此只能使出最終殺器： docker.

gitbook有官方的Docker Hub帳號，可是好像沒有官方的gitbook程序image。推薦第三方排名較高的billryan/gitbook。

在本機已有docker的狀況下，如此運行：

# 對當前文件夾進行gitbook初始化（容器在命令執行完後會自動消失 由於--rm選項）
$ docker run --rm -v "$PWD:/gitbook" -p 4000:4000 billryan/gitbook gitbook init

# 對當前文件夾的gitbook編譯並提供預覽（容器在命令執行完後會自動消失 由於--rm選項）
$ docker run --rm -v "$PWD:/gitbook" -p 4000:4000 billryan/gitbook gitbook serve

# build
$ docker run --rm -v "$PWD:/gitbook" -p 4000:4000 billryan/gitbook gitbook build

# 最高將docker變成alias快捷鍵，至關於本機的gitbook命令了
$ alias gitbook='docker run --rm -v "$PWD":/gitbook -p 4000:4000 billryan/gitbook gitbook'

以上docker會把當前文件夾映射爲虛擬系統裏的/gitbook文件夾，而且將4000端口映射到本機的4000.並且因爲--rm選項，docker不會存儲container。這樣一來就和本機安裝的gitbook沒什麼兩樣了。

本地項目建立及初始化：

# 初始化本地一個項目
$ cd book
$ gitbook init

# 編譯並預覽書籍（生成好後，會顯示一個本地連接，能夠在瀏覽器裏打開預覽）
$ gitbook serve

若是提示相似這樣的錯誤：Error: ENOENT: no such file or directory, stat '/gitbook/_book/gitbook/gitbook-plugin-lunr/lunr.min.js'
那麼就須要安裝插件。首先要在項目根目錄下新建一個book.json文件，內容以下：

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

而後運行命令gitbook install安裝這些插件。以後就應該沒問題了。

基本文件結構：
[站外圖片上傳中...(image-878a3d-1548159627560)]

Gitbook至少須要兩個文件:

• README.md：至關於書籍簡介
• SUMMARY.md：這個很是重要，定義了整個目錄結構和相應的文件連接

SUMMARY.md目錄文件格式：
Gitbook的目錄最多支持3級。

• 標準格式：

* [第一章](section1/README.md)
    * [第一節](section1/example1.md)
    * [第二節](section1/example2.md)
* [第二章](section2/README.md)
    * [第一節](section2/example1.md)

• 利用標題或分割線：

# Summary

### Part I

* [Introduction](README.md)
* [Writing is nice](part1/writing.md)
* [GitBook is nice](part1/gitbook.md)

### Part II

* [We love feedback](part2/feedback_please.md)
* [Better tools for authors](part2/better_tools.md)

----

* [Last part without title](part3/title.md)