GitBook 插件介绍及定制

在使用 GitBook 制作高质量电子书一文中我简要描述了 GitBook 的基本功能和使用，适用于 GitBook 的所有插件均可以从 Plugins for GitBook 中找到，下文将介绍一些适用于 GitBook 的实用插件及定制化操作，插件的编写将在随后一篇文章中详细介绍。

新增插件及配置

GitBook 中的插件及配置保存在电子书根目录下的 book.json, 以 algorithm-exercise/book.json 为例，

{
    "plugins": [
        "disqus",
        "ga",
        ...
        "algolia"
    ],
    "pluginsConfig": {
        "disqus": {
            "shortName": "algorithm4bill"
        },
        "ga": {
            "token": "UA-32317667-7"
        },
        ...
        "algolia": {
            "index": "algorithm",
            "applicationID": "9YBMOZR89J",
            "publicKey": "5860a3e55ee72831917b1b9e2a4649ca",
            "freeAccount": "true"
        }
    }
}

plugins 中是插件的名字，pluginsConfig 中则是针对插件的一些个性化设置。

在 GitBook v3 之后官方新增了行内评论功能，默认开启，较 disqus 这种根据 URL 整页进行评论的插件整合更为紧密，缺点是暂时不支持富文本如图片，同时多行评论的可读性比较差。较为通用的评论插件有 disqus, 导出和迁移都比较方便。

协作编辑

目前 GitBook 原生支持多作者共同编辑，但如果借助 GitHub 托管，则可以利用其 Pull Request 大大地降低协作的门槛，edit-link 插件非常好使，只是读者可能不那么容易发现…

搜索

默认的搜索功能聊胜于无，目前较为推荐的第三方搜索插件为 algolia，免费额度足够用了，使用 algolia 后默认的搜索插件即被替换。和 algolia 类似的有 Swiftype, 使用上较为简单，但目前不再提供免费账户故不推荐。

LaTeX 公式显示

latex

官方提供了 KaTeX 和 MathJax 两个可以书写 LaTeX 的插件，实测下来推荐 KaTeX, 网页上的渲染速度完爆 MathJax, 在 PDF 中的显示效果也堪称完美，缺点是对一些复杂的 LaTeX 公式支持不好，生成的 mobi 格式中多行复杂公式可读性很差。上图为 KaTeX 在 PDF/Website/ePub 上的显示效果。

访问统计及 sitemap

网站访问统计较为常见的有 Google Analytics. 对搜索引擎较为友好的可以考虑添加 sitemap, 官方的插件目前对多国语言支持有点问题，我修改过的插件名为 sitemap2.

订阅更新

官方提供的 subscribe 暂时只支持更新事件，并没有如 RSS 之类针对文章的更新，rss 插件虽然有针对文章的更新，但实际使用下来发现无法获取文章全文，针对这个问题我写了一个 feed 插件，支持 RSS 2.0 和 Atom, 使用上较 rss 插件也要简单，欢迎试用~

目录及标签/分类

etoc-tags

GitBook 的目录插件数不胜数，但自己用下来发现没有一款自己满意的，于是在中秋假期写了一个 etoc 根据文章层级在大标题后小标题前根据标题层次自动生成目录，可以自定义目录层次深度和对单页禁用。电子书除了分章节外有时也可能需要诸如分类/标签功能，tags 插件和 etoc 一样也是在中秋假期落地生根的。

插件项目主页

为便于读者查找以上所提插件的主页和配置，简要总结如下。

评论 - GitbookIO/plugin-disqus
GitHub 协作编辑 - rtCamp/gitbook-plugin-edit-link
搜索 - GitbookIO/plugin-algolia
公式 - GitbookIO/plugin-katex, GitbookIO/plugin-mathjax
统计 - GitbookIO/plugin-ga
网站地图 - GitbookIO/plugin-sitemap
网站地图多国语言修复版 - gitbook-plugin-sitemap2
订阅更新 - billryan/gitbook-plugin-feed, denysdovhan/gitbook-plugin-rss
页内目录生成 - billryan/gitbook-plugin-etoc
分类/标签 - billryan/gitbook-plugin-tags

进阶定制

除了使用插件丰富 GitBook 的功能外，如果使用 GitHub 托管电子书源码，你还可以借助 GitHub 提供的 webhook 进一步扩展，如借助 slack 将 git commit 和评论等一并整合，disqus 整合进 slack 我用了 Zapier 提供的服务。

字体字型

针对中文字型的复杂性，我在 Web 中对简体和繁体进行了区分，具体细节则是可以在 styles 目录下新建一名为 website.css 的文件，根据 GitBook 中 CSS 的优先级和特化特性，以简体中文为例，

.book .book-summary, .book .book-body  {
    font-family: "Microsoft YaHei UI", "Microsoft Yahei", "PingFang SC", "Lantinghei SC", "Hiragino Sans GB", "WenQuanYi Micro Hei", "WenQuanYi Zen Hei", "Noto Sans CJK SC", "Microsoft JhengHei UI", "Microsoft JhengHei", "PingFang TC", "Lantinghei TC", "Noto Sans CJK TC", "Helvetica Neue", Helvetica, Arial, sans-serif;
}

优化繁体中文的显示时可将繁体字型置于简体前即可，以上这些字型基本上涵盖了 Windows/Mac/Linux/iOS 等主流平台的最佳中文显示。

自定义 PDF/mobi/ePub 输出

曾几何时，GitBook 官方提供的 PDF/mobi/ePub 文件输出效果惨不忍睹，由于自己的电子书源码托管于 GitHub, 借助于免费的 travis, 你可以自定义编译脚本输出这些电子书，经过一番摸索，发现思源黑体非常适合简体及繁体中文显示，生成的 PDF 质量堪称完美，唯一的缺点就是生成的 PDF 文件体积略大，编译脚本见 .travis.yml 由于 travis 编译好的文件仅短暂存于第三方服务器中，因此还需要借助 Amazon s3/七牛/GitHub 托管静态资源，七牛比较方便大陆用户下载，加速效果明显。借助 GitHub 托管静态资源有些小的 trick, 用过 git 的人都知道用它托管二进制文件的苦，不久之后整个 repo 就会变得硕大无比，我在算法笔记的电子书中早期也犯过同样的错误，现在采用的方式为另建 GitHub 小号克隆后新建 deploy 分支专门用于发布编译好的 PDF/mobi/ePub, 原地更新不产生历史 commit, 进而解决了 repo 占用空间迅速变大的困扰。

除了使用 travis 在每次 git push 外你也可以考虑使用我打包好的 billryan/docker-gitbook 自行编译测试。

文章目录