GitHub Pages 与 Gitee Pages 上的 Jekyll

GitHub 与 Gitee 提供的 Pages 服务中，均内嵌了 Jekyll 支持（Gitee 还提供了 Hugo 与 Hexo 支持）。所谓「支持」，即指这些生成工具挂在云端；你只需要提供原始代码（如 Markdown 文档、Sass/Stylus/Less 样式表），再由 Pages 服务自动编译、部署即可。这样，搭建网站的技术门槛进一步下降，你只需要会两件事就能搭建网站了：

1. 会写 Markdown 文档；
2. 注册 GitHub 或 Gitee 账号，点点鼠标，在你的代码仓库中启用 Pages 服务。

因为技术门槛如此之低，导致不少用户压根就意识不到 Pages 服务内置了 Jekyll 工具，甚至以为每一个 Markdown 文档理所当然地就能变成一个网页。此外，另一个常被忽视的问题是：由 Pages 服务调用的 Jekyll 工具，并非最新版本，而且隐性地增添了许多插件，这可能使用户在本地使用 Jekyll 或迁移平台时碰上「不协调」的问题。最常见的一个问题就是：在 GitHub Pages 上正常生成的代码仓库，到 Gitee Pages 上就变得一团糟。这不是因为 Gitee Pages 的功能「不如」GitHub Pages，而是因为：

GitHub Pages 没有告诉你它们为自己的 Jekyll 多加了几个插件，Gitee Pages 也没有告诉你它们的 Jekyll 并没有这些插件。

这里对 GitHub Pages 与 Gitee Pages 所使用的 Jekyll 进行一个简单的分析（后面姑且简称为 GitHub Jekyll 与 Gitee Jekyll），以说明它们隐性地附加了哪些功能，需要特别注意。

Jekyll on GitHub Pages

GitHub Pages 中所采用的 Jekyll 及插件、依赖，被汇总到名为 github-pages 的 Gem 中（主页）。如果你在本地安装了这个 Gem，可以运行它来查看其所要求的各项依赖版本。以目前最新的 204 版本为例，在 shell 中运行：

$ github-pages versions
+------------------------------+---------+
| Gem                          | Version |
+------------------------------+---------+
| jekyll                       | 3.8.5   |
| jekyll-sass-converter        | 1.5.2   |
| kramdown                     | 1.17.0  |
| jekyll-commonmark-ghpages    | 0.1.6   |
| liquid                       | 4.0.3   |
| rouge                        | 3.13.0  |
| github-pages-health-check    | 1.16.1  |
| jekyll-redirect-from         | 0.15.0  |
| jekyll-sitemap               | 1.4.0   |
| jekyll-feed                  | 0.13.0  |
| jekyll-gist                  | 1.5.0   |
| jekyll-paginate              | 1.1.0   |
| jekyll-coffeescript          | 1.1.1   |
| jekyll-seo-tag               | 2.6.1   |
| jekyll-github-metadata       | 2.13.0  |
| jekyll-avatar                | 0.7.0   |
| jekyll-remote-theme          | 0.4.1   |
| jemoji                       | 0.11.1  |
| jekyll-mentions              | 1.5.1   |
| jekyll-relative-links        | 0.6.1   |
| jekyll-optional-front-matter | 0.3.2   |
| jekyll-readme-index          | 0.3.0   |
| jekyll-default-layout        | 0.1.4   |
| jekyll-titles-from-headings  | 0.5.3   |
| jekyll-swiss                 | 1.0.0   |
| minima                       | 2.5.1   |
| jekyll-theme-primer          | 0.5.4   |
| jekyll-theme-architect       | 0.1.1   |
| jekyll-theme-cayman          | 0.1.1   |
| jekyll-theme-dinky           | 0.1.1   |
| jekyll-theme-hacker          | 0.1.1   |
| jekyll-theme-leap-day        | 0.1.1   |
| jekyll-theme-merlot          | 0.1.1   |
| jekyll-theme-midnight        | 0.1.1   |
| jekyll-theme-minimal         | 0.1.1   |
| jekyll-theme-modernist       | 0.1.1   |
| jekyll-theme-slate           | 0.1.1   |
| jekyll-theme-tactile         | 0.1.1   |
| jekyll-theme-time-machine    | 0.1.1   |
+------------------------------+---------+

能看到其列出来一大串的 Gem。通过这个页面也可以看到 GitHub Pages 上的 Jekyll 版本及相关依赖。

以上这些 Gem，可以大致划分为四类：

1. Jekyll 及其依赖，比如 Sass 转换、Kramdown 引擎、Liquid 模板语言、Rouge 高亮器等等。这些算是常规构件，不可或缺。注意，目前 GitHub Pages 使用的 Jekyll 版本为 3.8.5，而最新版本是 4.0.0，有一个「适当」的延迟。
2. 为 GitHub Pages 定制的额外功能，主要有两个：jekyll-commonmark-ghpages，在 Commonmark 基础上改出来的 GFM 引擎（但 Jekyll 仍然默认用 Kramdown）；github-pages-health-check，用于检查域名（DNS 服务）和 GitHub Pages 服务是否正常。
3. 若干 Jekyll 插件，基本上都是 jekyll 开头。后面会详细分析。
4. 若干 Jekyll 主题，除了 Jekyll 的默认主题 minima 和一个基本主题 jekyll-swiss 之外，还有 13 个 jekyll-theme 开头的，它们就是你在 GitHub Pages 服务里即选即用的 13 个主题。

从以上后三类可以看到，GitHub Jekyll 其实「加持」了很多的辅助件，并不单纯。而这样多的辅助构件，最终营造出了前面所提的「每一个 Markdown 文档理所当然地可以变成一个网页」之幻觉。事实上，如果是纯粹用 Jekyll 搭建网站，所需要做的工作仍然是不少的。

下面再详细分析一下 GitHub Jekyll 所采用的插件。

Jekyll 的 Markdown 引擎

在 Maruku 停止更新后，Jekyll 的默认 Markdown 引擎变成了 Kramdown，同样也是一个用 Ruby 开发的工具。Kramdown 实现了相当多的拓展功能，典型者如 LaTeX 公式、行内属性标记等，拓展了用 Markdown 实现网页（HTML）的可能性。

GitHub Jekyll 也是默认用 Kramdown 渲染 Markdown，不过前面看到其也提供了一个 GFM 引擎。在 GitHub 的官方文档中对此有特别说明，并强调「只有使用后者才能保证网站效果与 GitHub 中（渲染的 Markdown 页面）的一样」。仔细想想，有这个需求的用户应该不在少数。

常规插件

在 GitHub Jekyll 所用插件之中，下面这些是比较常规、常见的（强调者表示默认启用）：

• jekyll-sitemap，用于生成站点地图文件 sitemap.xml 供搜索引擎抓取；
• jekyll-feed，用于生成 RSS 订阅链接 feed.xml；
• jekyll-coffeescript，CoffeeScript 转换器；
• jekyll-redirect-from，重定向插件，从功能上可以理解为 permalink 的反面；
• jekyll-paginate，分页器；
• jemoji，表情包；
• jekyll-avatar，提供了形如 {% avatar [username] %} 的标签，用于获取 GitHub 用户的头像；
• jekyll-remote-theme，使你能够使用挂在 GitHub 上的 Jekyll 主题；
• jekyll-gist，提供了形如 {% gist xxx %} 的标签，用于在页面上展示 Gist 的内容；
• jekyll-mentions，使得 GitHub 上的 @ 用户功能在网站中得到支持；
• jekyll-relative-links，能够将指向 Markdown 文档的链接转换为指向对应 HTML 页面的链接（有点鸡肋）。

其中许多算是 Jekyll 的标配插件，经常被使用。它们更多地是提供了一种可选项，不会对网站的生成效果有太大影响。

静默增强插件

除了上面所提的基本插件，另外的插件则非常「阴险」，默认启用，发挥了一些你根本意识不到的功能。包括：

• jekyll-seo-tag：定制了 {% seo %} 这个 Liquid 标签的功能。SEO 的其他方面不说，网站的