手把手教你使用 GitBook

一、简介

GitBook 是一个支持用 MarkDown 编写文档的软件，支持输出 HTML、PDF、eBook 格式文档。作为开发者我们一般会用它来写一些技术和接口文档。

GitBook 官网：https://www.gitbook.com

二、安装

1. 安装 Node.js

GitBook 是基于 Node.js 的命令行工具，需先下载安装 Node.js，检测是否安装成功：

$ node -v
v6.9.1

2. 安装 GitBook

使用 npm 安装 GitBook，命令如下：

$ npm install -g gitbook-cli

检测是否安装成功：

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

三、使用

1. 初始化

新建目录 book，在该目录下执行如下命令进行初始化：

$ 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.md 中的目录结构，然后再用 init 命令初始化，程序将会根据我们的目录结构生成目录和文件，目录结构示例：

# Summary

* [Introduction](README.md)
* [Chapter1](chapter1/README.md)
    * [Section1.1](chapter1/section1.1.md)
    * [Section1.2](chapter1/section1.2.md)
* [Chapter2](chapter2/README.md)

2. 生成并预览

book 目录下执行如下命令，将会生成 HTML 文件并提供预览地址：

$ gitbook serve
Live reload server started on port: 35729
Press CTRL+C to quit ...

info: 7 plugins are installed 
info: loading plugin "livereload"... OK 
info: loading plugin "highlight"... OK 
info: loading plugin "search"... OK 
info: loading plugin "lunr"... OK 
info: loading plugin "sharing"... OK 
info: loading plugin "fontsettings"... OK 
info: loading plugin "theme-default"... OK 
info: found 1 pages 
info: found 0 asset files 
info: >> generation finished with success in 1.0s ! 

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

在浏览器中打开 http://localhost:4000 即可看到初始化的文档。

如果只需生成 HTML 文件执行 build 命令即可，命令如下：

$ gitbook build

如果需要生成 PDF 文件，由于依赖 ebook-convert，需要安装 Calibre，安装配置完成后，执行如下命令即可：

$ gitbook pdf

3. 编辑器

现在支持实时预览的 markdown 编辑器有很多，可以根据自己的喜好选择，此处仅做推荐：

• 官方编辑器 GitBook Editor
• PhpStorm（不要问我为什么，我不会告诉你我是 PHP 程序猿）
• Sublime Text（其实我写 MD 文档都不用预览，所以没给它装插件，龇牙）

四、配置

通过配置 book.json 中的参数，我们可以配置文档的很多信息，比如标题、侧边栏、插件等。
一个简单的 book.json 文件如下：

{
    "title": "GitBook 使用教程",
    "author": "Yanlong Ma <json_vip@163.com>",
    "description": "GitBook 使用教程 - 马燕龙个人博客",
    "generator": "site",
    "links": {
        "sidebar": {
            "马燕龙个人博客": "https://www.mayanlong.com"
        }
    }
}

下面介绍的插件也需要用到该配置。

五、插件

1. 自带插件

GitBook 默认带有五个插件：highlight、search、sharing、fontsettings、livereload。如果要去除自带的插件，可以在插件名称前面加”-“，如下：

"plugins": ["-search"]

2. 命名规范

GitBook 还支持许多插件，可以从 NPM 上搜索 GitBook 的插件，GitBook 推荐插件的命名方式如下，所以可以通过以下两种方式来搜索 GitBook 的插件或者主题：

gitbook-plugin-X: 插件
gitbook-theme-X: 主题

3. 安装插件

下面介绍如何安装 gitbook-plugin-prism 插件，在 NPM 搜索该插件，插件主页链接为 https://www.npmjs.com/package/gitbook-plugin-prism。

首先安装该插件，命令如下：

$ npm i gitbook-plugin-prism

然后在 book.json 中添加该插件，同时禁用默认的 highlight，配置如下：

{
  "plugins": ["prism", "-highlight"]
}

可以根据自己的喜好，配置不同的主题：

"pluginsConfig": {
    "prism": {
        "css": [
            "prismjs/themes/prism-solarizedlight.css"
        ]
    }
}

本文首发于马燕龙个人博客，欢迎分享，转载请标明出处。
马燕龙个人博客：https://www.mayanlong.com
马燕龙个人微博：http://weibo.com/imayanlong
马燕龙Github主页：https://github.com/yanlongma