GitHub Pages 与 Gitee Pages 上的 Jekyll

Jekyll on GitHub Pages
Jekyll on Gitee Pages

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

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

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

这里对 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，可以大致划分为四类：

Jekyll 及其依赖，比如 Sass 转换、Kramdown 引擎、Liquid 模板语言、Rouge 高亮器等等。这些算是常规构件，不可或缺。注意，目前 GitHub Pages 使用的 Jekyll 版本为 3.8.5，而最新版本是 4.0.0，有一个「适当」的延迟。
为 GitHub Pages 定制的额外功能，主要有两个：jekyll-commonmark-ghpages，在 Commonmark 基础上改出来的 GFM 引擎（但 Jekyll 仍然默认用 Kramdown）；github-pages-health-check，用于检查域名（DNS 服务）和 GitHub Pages 服务是否正常。
若干 Jekyll 插件，基本上都是 jekyll 开头。后面会详细分析。
若干 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 的其他方面不说，网站的 <title> 元素就是它搞定的（使用了 _configs.yml 文件中的 title 和 description 属性）。所以在用 GitHub Jekyll 时要想改变网页标题的格式，就必须要求它停止输出标题：{% seo title=false %}，否则你会以为标题是「无中生有」的。
jekyll-github-metadata：用于从 GitHub 获取元信息，比如项目名称、作者之类的。它主要是给 GitHub Pages 生成的网站提供一些默认参数，比如上面的 SEO 插件就会使用 GitHub 仓库的项目名称、描述作为网站的标题和副标题。在本地用 Jekyll 构建 Pages 上的网站时，十有八九会出现「No GitHub API authentication」的警告，这个锅也得由它来背（它要用 GitHub API 来获取这些信息）。
jekyll-optional-front-matter：根据 Jekyll 的机制，其只会转换有 YAML 头信息（哪怕是空的）的 Markdown 文件，这个插件则取消了这一要求。所以如果你发现用在其他场合使用 Jekyll 时许多 Markdown 文件没有被转换，你会意识到这个插件的作用：让你不用写头信息。（另外，这个规则对 Sass 文件不使用，所以你得对自己写的、放在 _sass 目录以外的 Sass 文件至少给一个空的头信息。）
jekyll-readme-index：这个插件使得 Jekyll 在找不到 index.html 或 index.md 时，将 README.md 转换为 index.html 作为替代。这个功能的好处在于实现了 GitHub 页面预览和网站构建的统一，因为在 GitHub 页面上 README 的作用就相当于一般网站的 index.html。
jekyll-default-layout：帮助你自动给首页套 layout: home、给推送文章套 layout: post、给一般页面套 layout: page、实在不行就套 layout: default。作用很明显：让你不用写头信息。
jekyll-titles-from-headings：自动将一个没有指明 title 的 Markdown 文件之首级标题提取为 title。从页面显示来说，一个页面有没有 title 其实无关紧要，但需要生成网站导航、文章列表等的时候就必须确保每个页面都有 title。这个功能的作用也很明显：让你不用写头信息。

以上几个插件，都是「静默」生效；其中不少在 Jekyll 中并不默认启用，但它们在 GitHub Jekyll 中全都是默认启用的。它们发挥的作用，也许你之前从未意识到，但现在一看即知。

GitHub Pages 主题

GitHub Pages 提供的 13 个基本主题，也被包含在依赖当中，这意味着你不需要安装就能使用它们。它们在 _configs.yml 中用 theme 属性启用（也许这是许多人见过的第一行 YAML 代码？），这会给初学者造成一种误解，以为其他的主题也可以这样通过一行代码来使用。

事实上，如果要在 GitHub Jekyll 中使用其他主题，有这样两种办法：

启用 jekyll-remote-theme 插件，这样你就可以使用任意一个在 GitHub 上公开的 Jekyll 主题（其他地方的不行）；
把主题下载下来，将对应文件拷贝到指定位置——注意清理之前的主题。（Jekyll 的主题管理不是很灵活，不如 Hugo、Hexo 等工具。）

当然，如果你是在本地生成网站文件后再借 Pages 的服务器发布，方法就比较多了。

总结

经过以上对各个依赖的分析，我们可以发现：GitHub Jekyll 提供了相当多的辅助功能，极大的化简了网站的生成，而我们甚至还不自知。在不清楚这些背景的情况下，尝试从 GitHub Pages 服务下迁移出 Jekyll 项目，很有可能会踩坑，比如：

为什么这个 Markdown 文件没有被转换？（因为你没有写头文件，怪 jekyll-optional-front-matter）
为什么文章列表里的文章标题都是空的？（因为它们的标题是正文中的 h1 标签，没有写到头信息中的 title 里，怪 jekyll-titles-from-headings）
为什么这个路径下的页面不见了？（因为你原来用的是 README.md 转换成 index.html，怪 jekyll-readme-index）

当然，问题的可能性不多，一一排除总能解决。所以归结出一个结论：与其花时间琢磨上面这么多 Gem 的关系，还不如自己去踩踩坑。

坑归坑，好话也还是要说几句：如果只是一直用 GitHub Jekyll，以上这些都不算是问题，而算优势。「Markdown 文件自动变成网页」这样的好事，还是人人所欲的；它毕竟能让许多完全不了解前端技术的人构建一整个网站出来，应该算是大好事。

Jekyll on Gitee Pages

Gitee Pages 究竟用的是绿 Jekyll 还是花 Jekyll，没有公开信息，只能间接地寻找一些蛛丝马迹了。

尝试在一个 Gitee 仓库中启用了 Gitee Pages，发现它支持 jekyll-seo-tag，但在生成的 HTML 页面上赫然显示该插件版本为 2.3.0。经过检查，这个版本是 2017 年八月发布的，看来有些年头了。

但是仅从这一个插件不能推断出所有信息。为此，我又测试了其他几个插件，发现：

jekyll-sitemap、jekyll-feed 两个插件都可以正常使用，说明它们算是 Gitee Jekyll 的依赖。
另外，在 jekyll-feed 生成的 feed.xml 中意外发现了 Jekyll 的版本信息：3.6.2。检查发现这是 2017 年十月发布的版本。
jekyll-mentions 插件竟然可以用，指向 GitHub 的用户主页——自己做一个 Gitee 版本的应该也挺容易吧？跟 GitHub 有什么关系？
jemoji 用不了。
几个静默强化插件中，除了 jekyll-github-metadata 未启用之外，其他的都能正常工作。这造成的后果是，在 Gitee Pages 中必须自己写 baseurl，否则站点的样式表就找不着了，链接也会错乱。
jekyll-remote-theme 居然能用……前提是把 baseurl 写对。

根据以上的分析，可以得出以下几个结论：

Gitee Jekyll 的版本很旧了，一整套工具可能只是 2017 年末的「最新版」。找到了 Gitee Pages 的上线说明，发布时间是在 2018 年年中，差不太远（也许前端支持做好之后半年在做后端支持）。
Gitee Jekyll 跟 GitHub Jekyll 对接不良，迁移或同步的话得增补很多信息，并且不少插件用不了。
Gitee Jekyll 竟然支持 GitHub 上的远程主题，但是用起来似乎也存在若干问题，不稳定。

以上三条再归纳为一个最终的结论：（目前的）Gitee Jekyll 不可靠。为了用 Gitee Pages，只有在本地生成网站文件再发布了。和 GitHub Pages 比起来，这无疑抬高了使用门槛；这倒不算什么，重要的是在这种情况下 Gitee Jekyll 形同虚设，不会有什么人去用了。

冷嘲热讽不能解决问题。刚刚和 Gitee 管理团队联系上，表示将来会改进这些问题。持续关注。如果 Gitee Pages 的生态做出来了，肯定是也是一件大好事吧！