「效率工具」GitBook(3):插件与命令行工具

插件

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

默认插件

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

常用插件

Disqus

评论插件,地址:GitBook Plugins

1
2
3
4
5
6
"plugins": ["disqus"],
"pluginsConfig": {
"disqus": {
"shortName": "MatrixXT"
}
}

MathJax

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

1
"plugins": ["mathjax"]

打赏,地址:GitBook Plugins

1
2
3
4
5
6
7
8
9
10
11
"plugins": [
"donate"
],
"pluginsConfig": {
"donate": {
"alipay": "http://images.stanine.top/alipay.png",
"title": "等一杯咖啡,写稿到天亮!",
"button": "赏",
"alipayText": "支付宝打赏"
}
}

Copy-code-button

为代码块添加复制的按钮,地址:GitBook Plugins

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

Anchor-navigation-ex

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
"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 安装,运行下面的命令进行安装

1
npm install -g gitbook-cli

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

预览书籍

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

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

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

1
2
export DEBUG=true
gitbook build

其他命令

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

1
gitbook build --gitbook=2.0.1

列出本地所有的gitbook版本

1
gitbook ls

列出远程可用的gitbook版本

1
gitbook ls-remote

安装对应的gitbook版本

1
gitbook fetch 标签/版本号

更新到gitbook的最新版本

1
gitbook update

卸载对应的gitbook版本

1
gitbook uninstall 2.0.1

指定log的级别

1
gitbook build --log=debug

输出错误信息

1
gitbook builid --debug

参考

ChangeLog

  • 2018-07-28 初稿
「谢谢您支持」