GitBook 使用教程

背景

由于之前都把零散的知識都寫在 Gist 上，要查找的時候不是很系統(tǒng)化，所以打算挪到 GitBook 上來統(tǒng)一管理，而且 GitBook 寫完編譯后可以生成靜態(tài)頁面發(fā)布到博客上，逼格滿滿的樣子。

GitBook 簡介

GitBook 官網(wǎng)
GitBook 文檔

GitBook 準備工作

安裝 Node.js

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

$ node -v
v7.7.1

安裝 GitBook

輸入下面的命令來安裝 GitBook。

$ npm install gitbook-cli -g

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

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

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

安裝 GitBook 編輯器

去 GitBook 官網(wǎng) 下載 GitBook 編輯器；如果是 Mac 用戶且安裝過 brew cask 的話可以使用 brew cask install gitbook-editor 命令行來安裝 GitBook 編輯器。

先睹為快

GitBook 準備工作做好之后，我們進入一個你要寫書的目錄，輸入如下命令。

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

可以看到他會創(chuàng)建 README.md 和 SUMMARY.md 這兩個文件，README.md 應該不陌生，就是說明文檔，而 SUMMARY.md 其實就是書的章節(jié)目錄，其默認內容如下所示：

# Summary

* [Introduction](README.md)

接下來，我們輸入 $ gitbook serve 命令，然后在瀏覽器地址欄中輸入 http://localhost:4000 便可預覽書籍。

效果如下所示：

運行該命令后會在書籍的文件夾中生成一個 _book 文件夾, 里面的內容即為生成的 html 文件，我們可以使用下面命令來生成網(wǎng)頁而不開啟服務器。

gitbook build

下面我們來詳細介紹下 GitBook 目錄結構及相關文件。

目錄結構

GitBook 基本的目錄結構如下所示：

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

下面我們主要來講講 book.json 和 SUMMARY.md 文件。

book.json

該文件主要用來存放配置信息，我先放出我的配置文件。

{
    "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"
            }
        }
    }
}

相信很多節(jié)點自己也能猜到是什么意思，我還是簡單介紹下吧。

title

本書標題

author

本書作者

description

本書描述

language

本書語言，中文設置 "zh-hans" 即可

gitbook

指定使用的 GitBook 版本

styles

自定義頁面樣式

structure

指定 Readme、Summary、Glossary 和 Languages 對應的文件名

links

在左側導航欄添加鏈接信息

plugins

配置使用的插件

pluginsConfig

配置插件的屬性

SUMMARY.md

這個文件主要決定 GitBook 的章節(jié)目錄，它通過 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)