在項目實踐中，團隊需要對用到的知識技術進行總結，即便于分享，也利于傳承，而gitbook就是個不錯的選擇，使用gitbook-cli 對Markdown文檔進行編譯，生成靜態文件，再通過web服務器（e.g. nginx）對外提供服務。

gitbook和gitlab搭建持續集成，可實現文檔的即時更新，這也是我在DevOps實踐的一部分。

• https://www.gitbook.com

• https://github.com/GitbookIO/gitbook

環境搭建

1. 安裝 Node.js

gitbook 是一個基于 Node.js 的命令行工具，下載安裝 Node.js，安裝完成之后，你可以使用下面的命令來檢驗是否安裝成功。

$ node -v

2. 安裝 gitbook

輸入下面的命令來安裝 gitbook

npm install gitbook-cli -g

安裝完成之后，你可以使用下面的命令來檢驗是否安裝成功

$ gitbook -V

更多詳情請參照 gitbook 安裝文檔 來安裝 gitbook

3. 安裝 Gitlab Runner

下載二進制包

sudo curl -L --output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64

添加執行權限

sudo chmod +x /usr/local/bin/gitlab-runner

(可選)如果使用Docker，安裝Docker

curl -sSL https://get.docker.com/ | sh

創建 GitLab CI 用戶

sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash

以Service方式安裝

sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
sudo gitlab-runner start

4. 注冊Runner

• Runner安裝
• Runner注冊

運行以下命令

sudo gitlab-runner register

輸入GitLab 實例 URL Please enter the gitlab-ci coordinator URL

輸入Gitlab注冊的token (Gitlab admin權限才能看見)

Please enter the gitlab-ci token for this runner xxx

輸入Runner描述，后面可在Gitlab UI上更新

Please enter the gitlab-ci description for this runner

輸入Runner Tag，后面可在Gitlab UI上更新

Please enter the gitlab-ci tags for this runner (comma separated):

選擇Runner executor

Please enter the executor: ssh, docker+machine, docker-ssh+machine, kubernetes, docker, parallels, virtualbox, docker-ssh, shell: shell

gitbook 配置

1. 目錄結構

        .
        ├── book.json
        ├── README.md
        ├── SUMMARY.md
        ├── chapter-1/
        |   ├── README.md
        |   └── something.md
        └── chapter-2/
            ├── README.md
            └── something.md

• README.md
  gitbook第一頁內容是從文件 README.md 中提取的。如果這個文件名沒有出現在 SUMMARY 中，那么它會被添加為章節的第一個條目

• book.json
  該文件主要用來存放配置信息

• .bookignore
  將讀取.gitignore，.bookignore以及.ignore文件以獲得文件和文件夾跳過列表

• Glossary.md
  允許指定要顯示為注釋的術語及其各自的定義。根據這些條款，GitBook將自動構建一個索引并突出顯示這些術語

• SUMMARY.md
  用于存放GitBook的文件目錄信息，左側的目錄就是根據這個文件來生成的，默認對應的文件是 SUMMARY.md，可以在 book.json 重新定義該文件的對應值。它通過Markdown中的列表語法來表示文件的父子關系

  注意 不被SUMMARY.md包含的文件不會被gitbook處理

  SUMMARY.md示例：

  # Summary
  
  * [Introduction](README.md)
  * [Part I](part1/README.md)
      * [Writing is nice](part1/writing.md)
      * [gitbook is nice](part1/gitbook.md)
  * [Part II](part2/README.md)
      * [We love feedback](part2/feedback_please.md)
      * [Better tools for authors](part2/better_tools.md)
  

  通過使用 標題 或者 水平分割線 將 gitbook 分為幾個不同的部分，如下所示：

  # 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)
  

  目錄中的章節可以使用錨點指向文件的特定部分

  # Summary
  
  ### Part I
  
  * [Part I](part1/README.md)
      * [Writing is nice](part1/README.md#writing)
      * [gitbook is nice](part1/README.md#gitbook)
  * [Part II](part2/README.md)
      * [We love feedback](part2/README.md#feedback)
      * [Better tools for authors](part2/README.md#tools)
  

2. 命令行

1. gitbook init

   gitbook項目初始化,會自動生成兩個必要的文件 README.md 和 SUMMARY.md

2. gitbook build [path]

   構建gitbook項目生成靜態網頁，會生成一個 _book 文件夾（包含了 .md 對應的.html文件）

3. gitbook serve

   該命令實際上會首先調用 gitbook build 編譯 .md，完成以后會打開一個web服務器，監聽在本地的4000端口。

   生產的靜態文件可單獨放到tomcat或者nginx供靜態訪問

   ./
   ├── _book
   │   ├── gitbook
   │   │   ├── fonts
   │   │   ├── gitbook.js
   │   │   ├── gitbook-plugin-fontsettings
   │   │   ├── gitbook-plugin-highlight
   │   │   ├── gitbook-plugin-livereload
   │   │   ├── gitbook-plugin-lunr
   │   │   ├── gitbook-plugin-search
   │   │   ├── gitbook-plugin-sharing
   │   │   ├── images
   │   ├── index.html
   │   └── search_index.json
   ├── README.md
   └── SUMMARY.md
   

4. gitbook update #更新gitbook到最新版本

5. gitbook install #安裝依賴

6. gitbook builid --debug #輸出錯誤信息

7. gitbook build --log=debug #指定log級別

3. 插件

gitbook 提供了豐富插件，默認帶有 5 個插件，highlight、search、sharing、font-settings、livereload，如果要去除自帶的插件， 可以在插件名稱前面加 -，比如：

        "plugins": [
            "-search"
        ]

插件使用參考

• https://gitbook.zhangjikai.com/plugins.html

gitlab 與gitbook集成

.gitlab-ci.yml 示例：

# requiring the environment of NodeJS 10
image: node:10

# add 'node_modules' to cache for speeding up builds
cache:
  paths:
    - node_modules/ # Node modules and dependencies

before_script:
  - npm install gitbook-cli -g # install gitbook
  - gitbook fetch 3.2.3 # fetch final stable version
  - gitbook install # add any requested plugins in book.json

test:
  stage: test
  script:
    - gitbook build . public # build to public path
  only:
    - branches # this job will affect every branch except 'master'
  except:
    - master
    
# the 'pages' job will deploy and build your site to the 'public' path
pages:
  stage: deploy
  script:
    - gitbook build . public # build to public path
  artifacts:
    paths:
      - public
    expire_in: 1 week
  only:
    - master # this job will affect only the 'master' branch

參考

• http://www.chengweiyang.cn/gitbook/index.html