干货 | GitBook 插件介绍及定制

billryan 程序媛的日常 2016-11-22

GitHub 大神 billryan 又来啦!这次给大家介绍 GitHub 插件的定制啦!

以下是他今天分享的内容:

前文 干货 | 使用 GitBook 制作高质量电子书 中简述了 GitBook 的基本功能和使用,本文将介绍一些适用于 GitBook 的实用插件及定制化操作,适用于 GitBook 的插件均可以从 中找到,插件的编写实战将在随后一篇文章中详细介绍。鉴于微信公众号对外链限制较为严格,对 GitBook 有兴趣的朋友们可以点击文末“阅读原文”。

 

新增插件及配置

GitBook 中的插件及其配置保存在电子书根目录下的 `book.json`, 以插件 disqus ga 为例,


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

 

评论

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

 

协作编辑

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

 

搜索

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

 

LaTeX 公式显示


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

 

访问统计及 sitemap

网站访问统计较为常见的有 Google Analytics. 对搜索引擎较为友好的可以考虑添加 sitemap.

 

订阅更新

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

 

目录及标签/分类


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

- 订阅更新 - 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 提供的服务,借助 GitHub 提供的持续集成工具 travis 还可以进行深度定制。下图为我的算法笔记文档所使用的工作流,如果只是简单使用完全没必要使用这么复杂的方案...


 

字体字型

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


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


 

自定义 PDF/mobi/ePub 输出


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


除了使用 travis 在每次 git push 外你也可以考虑使用我打包好的 billryan/docker-gitbook 自行编译测试。进阶定制一节对细节并未作详细介绍,有兴趣的朋友可以留言评论进一步探讨。

以上就是今天的全部内容啦!大家下期见~

本站仅按申请收录文章,版权归原作者所有
如若侵权,请联系本站删除
觉得不错,分享给更多人看到