GitBook安裝部署實操手冊

前言

GitBook是一個基於Node.js的命令行工具，可使用Git和Markdown來編寫文檔，贊譽太多，不再贅述。

Node.js

1. 下載安裝包

cd /tmp

wget https://nodejs.org/dist/v12.16.1/node-v12.16.1-linux-x64.tar.xz

2. 解壓安裝包

tar xvf node-v12.16.1-linux-x64.tar.xz

3. 安裝

安裝過程分為3步：移動安裝包解壓目錄至/user/local、為node、npm建立軟鏈接，以及刪除安裝包。

mv node-v12.16.1-linux-x64 /usr/local/

ln -s /usr/local/node-v12.16.1-linux-x64/bin/node /usr/bin/node
ln -s /usr/local/node-v12.16.1-linux-x64/bin/npm /usr/bin/npm

rm -rf rm -rf node-v12.16.1-linux-x64.tar.xz

GitBook

參考鏈接：https://github.com/GitbookIO/gitbook/blob/master/docs/setup.md

安裝

npm install gitbook-cli -g

ln -s /usr/local/node-v12.16.1-linux-x64/bin/gitbook /usr/bin/gitbook

gitbook -V

gitbook-cli 是用於安裝、使用多個不同版本GitBook的工具。使用GitBook時會自動安裝需要的版本，比如：“gitbook -V”。

初始化

1. GitLab創建項目，命名為“wiki”，內容為空，克隆至本地；

git clone ssh://[e-mail]:2222/dip/wiki.git

GitLab創建項目的目的僅僅為Markdown文件的版本控制，不是必須選項，本地直接建立目錄也是可以的。

2. 初始化示例

gitbook init wiki

3. 預覽

執行以下命令：

cd wiki

gitbook serve

等待，看到如下信息：

Starting server ...
Serving book on http://localhost:4000

即可以通過瀏覽器訪問預覽效果，如下：

4. 后台啟動

mkdir -p /var/log/gitbook

gitbook serve >> /var/log/gitbook/serve.log 2>&1 &

目錄結構

鏈接參考：https://github.com/GitbookIO/gitbook/blob/master/docs/structure.md

 
基本的目錄結構，如下圖：

book.json

用於存儲配置信息（可選），簡單可以理解為配置文件，后續會涉及。

README.md

用於描述前言/說明信息（必須），簡單可以理解為主頁，按照Markdown格式編寫即可。

SUMMARY.md

用於描述章節列表（可選，建議必須），簡單可以理解為導航欄，接下來會介紹。

SUMMARY.md

鏈接參數：https://github.com/GitbookIO/gitbook/blob/master/docs/pages.md

 
SUMMARY.md格式實際是一個鏈接列表。鏈接的名稱就是章節的名稱，鏈接的目標就是章節文件路徑，如下圖：

“Part I”表示“章節1”，“part1/README.md”表示“章節1對應的文件路徑”；“Writing is nice”是“Part I”的子章節，“part1/writing.md”是相對應的文件路徑；“GitBook is nice”與“Writing is nice”相同。可以按照上述描述的層級格式繼續向下延展。我們可以使用目錄 + 子目錄的方式對章節文件進行歸檔。

插件

GitBook使用的插件及相應的配置需要通過 book.json指定，如下：

{
    "plugins": [
        "expandable-chapters-small",
        "-lunr",
        "-search",
        "search-plus",
        "-sharing",
        "splitter",
        "anchor-navigation-ex-toc",
        "hide-element",
        "insert-logo",
        "code"
    ],
    "pluginsConfig": {
        "hide-element": {
            "elements": [".gitbook-link"]
        },
        "insert-logo": {
            "url": "/images/dip.png",
            "style": "background: none; max-height: 120px; min-height: 120px"
        }
    }
}

配置文件的變更可能會導致GitBook進程重啟或異常終止，如上述插件配置調整，如果相應的插件沒有安裝完成，就會導致進程終止，需要安裝完成之后，再重新啟動。

插件安裝命令：

gitbook install

1. expandable-chapters-small

   章節導航支持多層目錄，並配置箭頭圖標，點擊箭頭才能實現收放目錄。

2. search-plus

   高級搜索，支持中文，使用此插件，需要將默認的 lunr 和 search禁用掉，即“-lunr”和“-search”。

3. sharing

   分享插件，默認開啟，禁用。

4. splitter

   擴展導航側邊欄，支持寬度可調節。

5. anchor-navigation-ex-toc

   為文章增加錨點目錄欄及回到頂部功能。

6. hide-element

   隱藏元素，如：“Published with GitBook”。

7. insert-logo

   左側導航欄上方插入Logo。

預覽

團隊協作

目前對GitBook了解有限，大致談下自己的想法：團隊成員可以通過GitLab將“wiki”克隆至本地，創建自己各自的寫作分支；編寫完成且本地啟動服務測試正常之后，可以提交並合並至Master。部署GitBook服務的服務器，部署Cron任務，定時Pull Master，保持同步更新。