使用 GitBook

GitBook 是一个提供 Markdown 书籍托管的网络平台， 支持通过 git 以及 GitHub 进行文档管理，使用它可以很简单地生成、发布电子图书。 同时，GitBook 也是一个 Node.js 命令行工具，可以使用它搭建自己的 GitBook 站点。

除了命令行程序和 web 服务外，GitBook 官方还提供了 跨平台的编辑器，提供直接编辑、发布电子书的功能， 不过实际上仅相当于自启动的 GitBook 控制台程序，并不推荐安装，尤其对于 *nix 系统而言。

GitBook 网站使用简单，这里就不再赘述了，GitBook 控制台提供强大的本地服务， 自启动的站点能够提供和网站完全一样的编辑服务，对于不方便登录其网站的用户来说非常方便。 GitBook 甚至提供 GitHub hook，在每一次 push 时自动更新书籍内容。

使用 GitBook 控制台程序

GitBook 控制台基于 Node.js，因此需要首先安装 Node.js 的包管理工具 npm，再通过 npm 安装 GitBook：

npm install -g gitbook-cli

如果你安装过 2.0.0 之前的版本，需要首先卸载 gitbook：

npm uninstall -g gitbook

安装成功后就可以使用 gitbook [options] [command] 来使用：

build [options] [source_dir] 根据文档目录构建书籍 serve [options] [source_dir] 构建并且提供书籍的 web 托管 install [options] [source_dir] 安装 GitBook 插件 pdf [options] [source_dir] 构建 pdf 格式的电子书 epub [options] [source_dir] 构建 ePub 格式的电子书 mobi [options] [source_dir] 构建 mobi 格式的电子书 init [source_dir] 根据 SUMARRY.md 文件的内容生成相应的目录和文件 publish [source_dir] 如果已绑定 GitBook.io，该命令可以直接发布书籍 git:remote [source_dir] [book_id] 为书籍设置远程 git 仓库

-h, --help 输出命令的使用说明 -V, --version 输出程序的版本号

目录结构

GitBook 目录必备一个 book.json 的文件作为插件配置，正如后缀名所示，是一个 JSON 格式的文件。

GitBook 插件

GitBook 插件本质上和 Node.js 包一样，因此其安装也分为全局和本地，全局安装命令： npm install plugin_name。本地安装则可以使用 GitBook 自带的命令 gitbook install 完成， 将自动安装 book.json 中所配置的插件，不需要任何参数，默认的安装目录是文档目录下的 ./node_modules/ 目录。因此建议将该目录加入 .gitignore 的忽略列表中。

###配置文件

标准的配置文件如下：

{
    // 输出目录
    // 可以被命令行覆盖
    // 不建议在 book.json 中使用该参数
    "output": null,

    // Generator to use for building
    // Caution: it overrides the value from the command line
    // 不建议在 book.json 中使用该参数
    "generator": "site",

    // 元数据（某些可以从 README 中提取）
    "title": null,
    "description": null,
    "isbn": null,

    // For ebook format, the extension to use for generation (default is detected from output extension)
    // "epub", "pdf", "mobi"
    // 可以被命令行覆盖
    // 不建议在 book.json 中使用该参数
    "extension": null,

    // 插件列表，可以使用 "-name" 删除默认插件
    "plugins": [],

    // 插件的全局设置
    "pluginsConfig": {
        "fontSettings": {
            "theme": "sepia", "night" or "white",
            "family": "serif" or "sans",
            "size": 1 to 4
        }
    },

    // 模板渲染参数
    "variables": {},

    // Links in template (null: default, false: remove, string: new value)
    "links": {
        // Custom links at top of sidebar
        "sidebar": {
            "Custom link name": "https://customlink.com"
        },

        // Sharing links
        "sharing": {
            "google": null,
            "facebook": null,
            "twitter": null,
            "weibo": null,
            "all": null
        }
    },

    // PDF 生成参数
    "pdf": {
        // 每页页脚是否添加页数
        "pageNumbers": false,

        // Font size for the fiel content
        "fontSize": 12,

        // PDF 文档大小
        // 可选参数：[u’a0’, u’a1’, u’a2’, u’a3’, u’a4’, u’a5’, u’a6’, u’b0’, u’b1’, u’b2’, u’b3’, u’b4’, u’b5’, u’b6’, u’legal’, u’letter’]
        "paperSize": "a4",

        // Margin (in pts)
        // 注：72 pts = 1 inch
        "margin": {
            "right": 62,
            "left": 62,
            "top": 36,
            "bottom": 36
        },

        //Header HTML template. Available variables: _PAGENUM_, _TITLE_, _AUTHOR_ and _SECTION_.
        "headerTemplate": null,

        //Footer HTML template. Available variables: _PAGENUM_, _TITLE_, _AUTHOR_ and _SECTION_.
        "footerTemplate": null
    }
}

官方插件

GitBook 官方提供了以下插件：

名称	功能描述
exercises	添加可交互的习题。
quizzes	添加可交互的选择题
mathjax	添加数学表达式支持
mixpanel	Mixpanel 数据追踪服务
infinitescroll	Infinite Scrolling

第三方插件

名称	功能描述
Google Analytics	Google Analytics 追踪服务
Disqus	Disqus 评论插件
Autocover	自动生成书本封面
Transform annoted quotes to notes	对 Markdown 引用进行二次渲染
Send code to console	在浏览器控制台中执行 JavaScript
Bootstrap JavaScript 插件	在 GitBook 中使用 Bootstrap JavaScript 插件
Piwik Open Analytics	Piwik Open Analytics 数据追踪服务
Heading Anchors	标题上添加 GitHub 风格的锚点链接
JSBin	在 GitBook 中嵌入 JS 终端
GrVis	将 Markdown 文本转为 svg 格式的 Graphviz 图
PlantUml	根据 Markdown 内容生成 svg 格式的 UML 图片
Mermaid	通过 mermaid 渲染流程图、示意图

更多插件

你可以在官方插件中心 或者 npm 寻找更多插件。

序列图插件

JS Sequence Diagram 插件 是一个 GitBook 生成序列图的插件，这里以它为例讲解如何安装插件。

首先在配置文件中加入插件名 js-sequence-diagram，不包括 gitbook- 那部分：

{
  "plugins": ["js-sequence-diagram"]
}

然后使用 gitbook 控制台工具安装：gitbook install。

JS Sequence Diagram 的基本使用如下：

Title: 标题

A->B: 直线
B-->C: 虚线
C->>D: 箭头
D-->>A: 虚线箭头

效果：

Title: 标题

A->B: 直线
B-->C: 虚线
C->>D: 开箭头
D-->>A: 虚线开箭头

JS Sequence Diagram 的更多使用请移步其文档。