GitBook 本地安裝和使用

GitBook 是一個基於 Node.js 的現代化文檔平臺，可使用 Github/Git 和 Markdown 來製作精美的電子書。

一、GitBook 本地安裝和使用教程

1. 全局安裝 gitbook 腳手架

$ npm install gitbook-cli -g

2. 檢查是否安裝成功

$ gitbook -V
CLI version: 2.3.2
GitBook version: 3.2.3

我在執行這一步的時候會安裝 gitbook，安裝期間遇到了 xcode-select: error: tool 'xcodebuild' requires Xcode, but active developer directory '/Library/Developer/CommandLineTools' is a command line tools instance 這樣的報錯信息，不用管，不影響後面的使用。

3. 創建一個空文件夾，然後執行

$ gitbook init
warn: no summary file in this book
info: create README.md
info: create SUMMARY.md
info: initialization is finished

這時會創建 README.md 和 SUMMARY.md 兩個文件。SUMMARY.md 是目錄，README.md 是目錄中的標題指向的文檔。

4. 開啓 gitbook 服務（適合寫文檔時使用）

$ gitbook serve

這時候 gitbook 會開啓一個本地服務，你就可以通過 http://localhost:4000 進行預覽文檔了。

當然，你也可以自己指定端口：

$ gitbook serve --port 2333

5. 生成靜態文檔（適合平時查看文檔時使用）

$ gitbook build

默認將生成的靜態文檔輸出到 _book 目錄（執行 gitbook serve 時也會生成此目錄）。

然後用瀏覽器打開 _book 目錄下的 index.html 進行查看就行了。

二、GitBook 的目錄結構

GitBook 基本的目錄結構如下：

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

book.json

該文件用來存放 gitbook 的配置信息。

{
    "title": "Blankj's Glory",
    "author": "Blankj",
    "description": "select * from learn",
    "language": "zh-hans",
    "gitbook": "3.2.3",
    "styles": {
        "website": "./styles/website.css"
    },
    "structure": {
        "readme": "README.md"
    },
    "links": {
        "sidebar": {
            "我的狗窩": "https://blankj.com"
        }
    },
    "plugins": [
        "-sharing",
        "splitter",
        "expandable-chapters-small",
        "anchors",

        "github",
        "github-buttons",
        "donate",
        "sharing-plus",
        "anchor-navigation-ex",
        "favicon"
    ],
    "pluginsConfig": {
        "github": {
            "url": "https://github.com/Blankj"
        },
        "github-buttons": {
            "buttons": [{
                "user": "Blankj",
                "repo": "glory",
                "type": "star",
                "size": "small",
                "count": true
                }
            ]
        },
        "donate": {
            "alipay": "./source/images/donate.png",
            "title": "",
            "button": "讚賞",
            "alipayText": " "
        },
        "sharing": {
            "douban": false,
            "facebook": false,
            "google": false,
            "hatenaBookmark": false,
            "instapaper": false,
            "line": false,
            "linkedin": false,
            "messenger": false,
            "pocket": false,
            "qq": false,
            "qzone": false,
            "stumbleupon": false,
            "twitter": false,
            "viber": false,
            "vk": false,
            "weibo": false,
            "whatsapp": false,
            "all": [
                "google", "facebook", "weibo", "twitter",
                "qq", "qzone", "linkedin", "pocket"
            ]
        },
        "anchor-navigation-ex": {
            "showLevel": false
        },
        "favicon":{
            "shortcut": "./source/images/favicon.jpg",
            "bookmark": "./source/images/favicon.jpg",
            "appleTouch": "./source/images/apple-touch-icon.jpg",
            "appleTouchMore": {
                "120x120": "./source/images/apple-touch-icon.jpg",
                "180x180": "./source/images/apple-touch-icon.jpg"
            }
        }
    }
}

• language：本書語言，中文設置 "zh-hans" 即可
• gitbook：指定使用的 GitBook 版本
• styles：自定義頁面樣式
• structure：指定 Readme、Summary、Glossary 和 Languages 對應的文件名
• links：在左側導航欄添加鏈接信息

SUMMARY.md

這個文件主要決定 GitBook 的章節目錄，它通過 Markdown 中的列表語法來表示文件的父子關係，下面是一個簡單的示例：

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

三、插件

GitBook 有 插件官網，默認帶有 5 個插件，highlight、search、sharing、font-settings、livereload，如果要去除自帶的插件， 可以在插件名稱前面加 -，比如：

"plugins": [
    "-search"
]

如果要配置使用的插件可以在 book.json 文件中加入即可，比如我們添加 plugin-github，我們在 book.json 中加入配置如下即可：

{
    "plugins": [ "github" ],
    "pluginsConfig": {
        "github": {
            "url": "https://github.com/your/repo"
        }
    }
}

然後在終端輸入 gitbook install ./ 即可。

如果要指定插件的版本可以使用 [email protected]，因爲一些插件可能不會隨着 GitBook 版本的升級而升級。