gitbook 作用是用来把md文件转换为一本带目录的书。转换格式可以是html，或者pdf等。

1.1. 一、简单使用gitbook：

1.1.1. 1、安装gitbook。

npm install -g gitbook-cli

1.1.2. 2、初始化一本(根据目录生成图书结构)。

新建一个目录，存放要写的书的md文件。我这里是mybook，在mybook中执行下面的命令。

gitbook init

会生成下面的2个文件。其中SUMMARY.md最终生成书的目录。README.md生成书的简介。

gitbook init 执行后，如果没有SUMMARY.md会创建一个SUMMARY.md。如果有会根据SUMMARY.md的目录结构创建对应的md文件。

1.1.3. 3、根据md文件生成summary目录.

如果自己有md文件。要生成summary目录。

npm install -g gitbook-summary

安装完之后，执行命令book sm，生成目录。作用实际上就是把原来的summary.md删除掉，再根据文档生成新的summary.md。

1.1.4. 4、预览书。

编写好md文档之后。在mybook目录中执行下面的命令。

gitbook serve

就会在mybook目录下面生成 _book文件夹（里面是html静态文件）。并且启动了一个web服务器。访问http://localhost:4000就可以看到书的效果。

1.1.5. 5、生成html。

也可以不预览，执行命名gitbook build 可以在mybook目录下面生成 _book文件夹（里面是html静态文件）。如果自己有web服务器，把_book文件夹复制到自己的服务器下面即可（首页是_book文件夹中的index.html）。

1.1.6. 6、生成pdf：

参考文档：
执行命令gitbook pdf就会生成pdf。如果报下面的错：

EbookError: Error during ebook generation: 'ebook-convert' is not recognized as an internal or external command,
operable program or batch file.

原因是GitBook在生成PDF的过程中使用到calibre的转换功能，没有安装calibre或安装了calibre没有配置环境变量都会导致转换PDF失败。要去 https://calibre-ebook.com/download 下载calibre并安装。

生成完成后在mybook/book.pdf

1.2. 二、配置gitbook-定制书的界面：

我们可以mybook目录下增加一个文件book.json，来配置gitbook控制书的一些界面。比如book.json有下面内容：

{
    "title": "这是一个测试文档",
    "description": "这是一个测试api文档",
    "author": "wk",
    "language": "zh-hans",
    "gitbook": "3.2.3",
    "links":
    {
        "sidebar":
        {
            "开发环境swagger": "https://xxxx"
        }
    },
    "plugins": [
        "-sharing"
    ]
}

title：显示到数的标题上，如下：
sidebar 定义显示到左边的导航。如下：
plugins：配置或取消插件。插件前面加中划线表示取消插件。
如-sharing 表示取消掉分享的按钮。如下：

1.3. 三、插件的使用：

1.3.1. 1、插件在哪里找到。

gitbook官方插件列表：https://plugins.gitbook.com/browse 在里面可以搜索各种插件。

1.3.2. 2、安装插件。

上面插件列表中，我找了一个versions-select插件，在book.json中配置如下：

{
    "title": "测试文档",
    "description": "测试api文档",
    "author": "wk",
    "language": "zh-hans",
    "gitbook": "3.2.3",
    "links":
    {
        "sidebar":
        {
            "开发环境swagger": "https://xxx"
        }
    },
    "plugins": [
        "-sharing",
        "versions-select"

    ],
    "pluginsConfig":
    {
        "fontsettings":
        {
            "theme": "night"
        },
        "versions": {
          "options": [
            {
              "value": "/v0.0.10/",
              "text": "v0.0.10"
            },
            {
              "value": "/v0.0.6/",
              "text": "v0.0.6"
            },
            {
              "value": "/v0.0.5/",
              "text": "v0.0.5"
            }
          ]
        }
    }
}

versions-select插件具体的配置要参照versions-select插件文档。
gitbook 方式安装插件。
上面我配置了一个versions-select插件。可以在mybook目录下运行命令gitbook install安装所有在book.json文件中配置的插件。安装完成后可以在mybook/node_modules目录看到。（把gitbook看做一个web项目，实际上就是安装了一个js依赖包。）
npm安装插件：不必预先在book.json中配置插件。可以使用npm安装插件。
```
npm i gitbook-plugin-versions-select
```
运行之后效果如下：
增加了版本的选择框。

下面的versions--options--value生成了下拉框的value值。

1.4. 参考文档：

https://blog.csdn.net/lu_embedded/article/details/81100704
配置gitbook：
http://gitbook.zhangjikai.com/structure.html
bug解决：
https://segmentfault.com/q/1010000009569245/a-1020000010696733
官方文档：
https://toolchain.gitbook.com/config.html
https://github.com/GitbookIO/gitbook
说的最全面：
https://juejin.im/post/5ce51e126fb9a07ed440d7d0

1、gitbook 的使用