使用gitbook完成一个文档站

介绍

GitBook 是基于 Node.js 的开源命令行工具，用于输出漂亮的电子书。

GitBook 支持 Markdown 和 AsciiDoc 两种语法格式，能够输出 html，pdf，epub，mobi等多种格式。

特性

• Markdown 或 AsciiDoc 语法
• 多类型支持：网站(html)或电子书 (pdf, epub, mobi)
• 多语言
• 目录、大纲
• 封面
• 模板和变量
• 模板继承
• 插件
• 主题

安装

全局安装 gitbook-cli 命令行工具，用于 gitbook 文档生成、构建等。

npm install gitbook-cli -g

查看版本：

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

环境依赖

gitbook 依赖 nodejs 版本，推荐使用 12.18.1 的 nodejs 版本，其他低或高版本可能会运行出错。

初始化项目

创建一个空目录，如：demo，然后进行目录进行初始化操作

gitbook init

会创建以下两个文件：

README.md（默认页） 和 SUMMARY.md（目录配置）

启动项目

gitbook serve

构建

gitbook build

构建后会生成 _book 目录，这个就是用来部署到服务器上的。

基本配置

添加配置需要创建 book.json 文件，把相关的配置放进去，如：

{
  "title": "demo文档",
  "description": "demo文档描述",
  "language": "zh-hans",
  "styles": {
    "website": "styles/website.css"
  }
}

插件使用

插件也是放到 book.json 中配置的，可以先配置好插件，然后 gitbook install 一键安装。

{
    "title": "demo文档",
    "description": "demo文档描述",
    "plugins": {
        "favicon",
        "prism"
    },
    "pluginsConfig": {
        "favicon": {
        "shortcut": "assets/images/logo.svg"
      },
      "prism": {
        "css": [
          "prismjs/themes/prism-tomorrow.css"
        ]
      }
    }
}

也可以通过 npm 安装，需要加上插件前缀 gitbook-plugin- ，这是gitbook插件的约束，如：

npm i gitbook-plugin-favicon

注意：安装后也是需要添加相应配置的，其他插件可以通过 gitbook-plugin- 来搜索。

在线示例

https://gofiber.fenxianglu.cn/

示例下载（含常用插件）

下载地址：https://ziyuan.fenxianglu.cn/detail/23

参考链接：

• https://www.mapull.com/gitbook/comscore/custom/plugin/common/toc.html
• http://www.zhaowenyu.com/gitbook-doc/plugins/cat-side-nav.html