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

新增插件及配置

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
"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 一样也是在中秋假期落地生根的。

插件项目主页

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

进阶定制

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

字体字型

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

1
2
3
.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 文件体积略大,编译脚本见 https://github.com/billryan/algorithm-exercise/blob/master/.travis.yml 由于 travis 编译好的文件仅短暂存于第三方服务器中,因此还需要借助 Amazon s3/七牛/GitHub 托管静态资源,七牛比较方便大陆用户下载,加速效果明显。借助 GitHub 托管静态资源有些小的 trick, 用过 git 的人都知道用它托管二进制文件的苦,不久之后整个 repo 就会变得硕大无比,我在算法笔记的电子书中早期也犯过同样的错误,现在采用的方式为另建 GitHub 小号克隆后新建 deploy 分支专门用于发布编译好的 PDF/mobi/ePub, 原地更新不产生历史 commit, 进而解决了 repo 占用空间迅速变大的困扰。

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

Comment and share

作为知识型工作者,时常会遇到的一个问题是如何将自己所做的工作精心汇总并便利地展示给广大读者。从阅读、传播和互动的角度来看,制作一个专业的网站可能是较为理想的方案,但实际操作起来可能会因为各种各样的技术问题而让人望而却步。GitBook 的出现算是解决了用户的绝大部分痛点。与 GitHub Pages 仅作为静态页面展示平台不同,GitBook 在文本编辑、多人协作、互动和电子书最终输出形式等方面的支持非常完善,基本上涵盖了现代出版物的整个生命周期,接下来的篇幅将详述这几个环节并介绍一些自己的实践经验。GitBook 的官方文档见 GitBook Toolchain Documentation

GitBook website

客户端或 Web

GitBook editor

相比于 GitHub Pages 高门槛的写作方式,GitBook 在这方面则显得亲民的多(和 Word Office 之类的软件易用程度相当),由于是基于 Node.js 的应用,其不仅提供跨平台的图形化写作软件,同时也提供了 Web 版在线编辑,两者在功能上无异。虽然 GitBook 同时支持 Markdown 和 AsciiDoc, 但可以明显感受到其对 Markdown 格式的偏爱,不熟悉 Markdown 的朋友们也不用担心,GitBook 的工具栏中提供了各种常用格式的快捷方式。Markdown 相比 LaTeX 来说要简单地多,需要记的格式最多也只有十来种,基本上是那种一看就会用的极简格式,详细的格式支持和使用见 Markdown

GitBook template

在 GitBook 网站新建电子书时可从默认的三种模板 (书籍或手册/API 文档/知识库 FAQ) 选择一个,官方虽然只提供了三种模板,但由于 GitBook 的可定制性极强,已经有不少第三方的模板可选了。除新建外你也可以从已有的 docs/odt/html/GitHub 等地方导入,从第三方导入的格式往往和 GitBook 家的稍微有那么点不一样,可能需要微调。

绑定 GitHub repo

除了使用客户端和 Web 编辑文本这种简易模式外,你也可以挑战一下 Hard 模式如通过绑定 GitHub repo 推送更新,需要注意的是绑定到 GitHub repo 后当前电子书不可再从客户端或者 Web 上更新,这大概是 git 的锅了吧 :( 使用 GitHub 绑定的电子书在添加新文件时容易忘记更新目录文件 SUMMARY.md,在此特意提醒下。

Continue reading

最开始使用 GitBook 撰写电子书是从去年开始维护的 billryan/algorithm-exercise 算法文档开始的,因为这个项目我已经造了不少轮子,给 GitBook 添加类似博客中的 category/tag 功能的插件在下班后的周末抽空写了写,趁这个中秋小长假美化了 CSS, 修了修 bug. 下文先介绍如何使用 gitbook-plugin-tags 插件,随后介绍自己实现这个插件的全过程。

使用

预览网站 ==> https://yuanbin.gitbooks.io/test/content/

根目录下手动新建tags.md

由于 GitBook 在 2.0.0 之后就将 summary 的 hook 移除了,所以目前需要先在根目录下新建 tags.md 文档并将其置于 SUMMARY.md 的最末尾。以某文件夹为例:

1
2
3
4
5
6
7
8
en
├── README.md
├── SUMMARY.md
├── faq
│   ├── README.md
│   ├── contributors.md
│   └── guidelines_for_contributing.md
└── tags.md

其中 SUMMARY.md 的内容如下:

1
2
3
4
5
6
7
# Summary
* [Preface](README.md)
* [FAQ](faq/README.md)
* [Guidelines for Contributing](faq/guidelines_for_contributing.md)
* [Contributors](faq/contributors.md)
* [Tags](tags.md)

切记* [Tags](tags.md)务必位于 SUMMARY.md 的末尾,因为 GitBook 是按顺序解析渲染的。

tags.md 中的内容自定,比如可以只包含一行 # Tags 作为标题。

新增 tags

tags 标记可以使用 YAML 在 markdown 源文件的前导处加入,如

1
2
3
4
5
---
tags: ['tag1', 'tag2', 'tag3 is here']
---
# FAQ - Frequently Asked Question
...

也可在正文中以单独一行表示,tag 之间以逗号分隔,tags 一定要在一行的开头,否则不予解析。

1
2
3
# FAQ - Frequently Asked Question
tags: tag1, tag2, tag3 is here

在正文中出现的 tag 格式要求相对较为随意,最关键的是一行开头要有 tags:, 不同 tag 以逗号分隔。

book.json 中新增 tags 插件

plugins 内增加 tags 即可,无需其他配置。

1
2
3
4
5
6
{
"plugins": [
"...",
"tags"
]
}

实现

功能设计

受 Hexo 博客引擎启发,tags 应该单独有一页面,该页面包含各 tag 所在的原网页链接,原网页链接则包含指向 tags.html 的链接,页面内容较多时需要使用定位符直接跳转到指定位置。简化起见,这里不为每个 tag 生成新页面,而是所有 tag 在一个 tags.html 页面中显示,利用 # 定位不同标签名。综合下来有两大基本需求:

  1. 源文档中的 tags: 处应能指向 tags.html 的链接,并根据不同 tag 以 # 加速定位
  2. tags.html 中应能包含不同 tag 所指向的原网页链接。

除了以上两个基本需求外,此插件最好能支持多国语言,同时用户设置 tag 信息时应比较人性化,显示 tag 最好能美观大方一些,而不是纯文字链接,俗话来说就是要讲究用户体验。

生成 tags.html

由于 GitBook 是从 SUMMARY.md 中提取 markdown 进行解析渲染的,所以在没找到直接调用解析生成 tags.html 的方法之前还是需要用户在根目录下新建 tags.md 并将其置于 SUMMARY.md 末尾,这样我们就能充分利用 GitBook 解析生成 tags.html 了。如果不在 SUMMARY.md 中添加 tags.md, 那么我们要么能在 GitBook 读取 summary 之前用程序加进去,要么能直接渲染生成 tags.html 静态文件。summary 的 hook 在 2.0.0 之后便被移除,直接渲染的方法一时也没有看到,所以折中下来暂时只能先麻烦下用户了。

CSS 美化

自己不是专业的设计师,所以参考了 https://hexo.io 和自己博客的主题,结合了 fontawesome 字体,取消了逗号分隔,为每个 tag 加了边框等等细节,看起来总算是舒服了一点点。由于在 markdown 中添加 div 标签等信息不太方便,这里我用了预加入 <!-- tags --> 信息以方便后期 HTML 中添加 tags 等 id 和 class.

多国语言

与 sitemap 插件不同,该插件多国语言的支持在于巧妙利用了浏览器和 markdown 解析器的寻址方式,用户浏览时会自动补全前面的网址等信息。

定位符直接定位

借助 github-slugid, 我们可以很方便的在 GitBook 中根据不同 header 生成相应的定位符。

正则匹配

之前正则匹配用的不熟,这次发现 JavaScript 中字符串的操作用正则实现十分便利,尤其是 /im 的引入可使得每一行单独处理而不是一次处理整个 page.content.

如果你喜欢我这个插件,不妨给这个项目 billryan/gitbook-plugin-tags 加一颗星吧 :)

Comment and share

Author's picture

Yuan Bin

Quality Matters
http://www.yuanbin.me


Software Developer


China, Shanghai