GitBook 使用教程

 

背景

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

GitBook 簡介

• GitBook 官網
• 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 官網 下載 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 

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

# Summary

* [Introduction](README.md) 

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

效果如下所示：

 

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

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

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

title

本書標題

author

本書作者

description

本書描述

language

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

gitbook

指定使用的 GitBook 版本

styles

自定義頁面樣式

structure

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

links

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

plugins

配置使用的插件

pluginsConfig

配置插件的屬性

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 ./ 即可。

如果要指定插件的版本可以使用 plugin@0.3.1，因為一些插件可能不會隨着 GitBook 版本的升級而升級。

結語

這是我對 GitBook 使用的總結，希望能幫到今后需要的小伙伴。