「效率工具」GitBook（3）：插件与命令行工具

插件

您可以在Plugins for GitBook查找适合自己的插件和用法，多数插件是针对书籍模式。

默认插件

highlight：高亮文本
search：为您的书添加了一个交互式搜索栏
sharing：右上角的分享按钮
fontsetting：添加字体、风格和背景设置按钮
lunr：为搜索插件提供了一个后端

常用插件

Disqus

评论插件，地址：GitBook Plugins

"plugins": ["disqus"],
"pluginsConfig": {
    "disqus": {
        "shortName": "MatrixXT"
    }
}

MathJax

数学公式渲染，您可以在公式两端加上$$，以让插件识别数学公式，地址：GitBook Plugins

"plugins": ["mathjax"]

Donate

打赏，地址：GitBook Plugins

"plugins": [
    "donate"
],
"pluginsConfig": {
    "donate": {
        "alipay": "https://xieting-img.oss-cn-hangzhou.aliyuncs.com/alipay.png",
        "title": "等一杯咖啡，写稿到天亮！",
        "button": "赏",
        "alipayText": "支付宝打赏"
    }
}

Copy-code-button

为代码块添加复制的按钮，地址：GitBook Plugins

"plugins": ["copy-code-button"]

Anchor-navigation-ex

添加 Toc 到侧边悬浮导航以及回到顶部按钮等功能，该插件支持以下参数的配置（这里展示的配置都是默认配置），地址：GitBook Plugins

"showLevel": true,
"associatedWithSummary": true,
"printLog": false,
"multipleH1": true,
"mode": "float",
"float": {
    "showLevelIcon": false,
    "level1Icon": "fa fa-hand-o-right",
    "level2Icon": "fa fa-hand-o-right",
    "level3Icon": "fa fa-hand-o-right"
},
"pageTop": {
    "showLevelIcon": false,
    "level1Icon": "fa fa-hand-o-right",
    "level2Icon": "fa fa-hand-o-right",
    "level3Icon": "fa fa-hand-o-right"
}

showLevel: boolean 标题是否显示层级序号，页面标题和导航中的标题都会加上层级显示。

associatedWithSummary: boolean 页面内的序号是否与 summary.md 中官方默认主题生成的序号相关联。

printLog: boolean 是否打印处理日志,在排查生成 book 失败的时候很有用，能知道是哪一个文件出的错。

详情见：插件地址、更详细说明。

其他插件

插件太多影响速度，够用就好。参考插件 · GitBook 使用教程，整理使用插件如下。

如何开发插件，请看：Plugins · GitBook Toolchain Documentation

代码块

图表

页面结构

文本

其他

GitBook 命令行工具

安装 GitBook 命令行工具

环境要求：NodeJS(v4.0.0 及以上)

通过 npm 安装，运行下面的命令进行安装

npm install -g gitbook-cli

gitbook-cli是 GitBook 的命令行工具，gitbook-cli 会将下载的 gitbook 的不同版本放到 ~/.gitbook中, 可以通过设置GITBOOK_DIR环境变量来指定另外的文件夹。

预览书籍

您可以在书籍根目录下，使用gitbook serve命令会运行一个服务器，通过http://localhost:4000/预览书籍。运行该命令后会在书籍的文件夹中生成一个 _book 文件夹，里面的内容是生成的 html 文件。您也可以使用gitbook build命令来生成网页而不开启服务器。

-o, --output <directory> 输出文件件, 默认为 ./_book
-f, --format <name> 产生的书籍的类型, 默认为静态站点, 可用的格式为: site, page, ebook, json
--config <config file> 配置文件, 默认为 book.js 或 book.json

您可以用此操作来调试book.json中的配置信息，调试成功后再 push 到远程仓库。增加环境变量 DEBUG=true 来得到更好的错误信息(包含错误堆栈)。

export DEBUG=true
gitbook build

其他命令

生成时指定 gitbook 的版本, 本地没有会先下载

gitbook build --gitbook=2.0.1

列出本地所有的 gitbook 版本

gitbook ls

列出远程可用的 gitbook 版本

gitbook ls-remote

安装对应的 gitbook 版本

gitbook fetch 标签/版本号

更新到 gitbook 的最新版本

gitbook update

卸载对应的 gitbook 版本

gitbook uninstall 2.0.1

指定 log 的级别

gitbook build --log=debug

输出错误信息

gitbook builid --debug

参考

ChangeLog

2018-07-28 初稿