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 与 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 的其他方面不说,网站的 <title> 元素就是它搞定的(使用了 _configs.yml 文件中的 titledescription 属性)。所以在用 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.htmlindex.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 中使用其他主题,有这样两种办法:

  1. 启用 jekyll-remote-theme 插件,这样你就可以使用任意一个在 GitHub 上公开的 Jekyll 主题(其他地方的不行);
  2. 把主题下载下来,将对应文件拷贝到指定位置——注意清理之前的主题。(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-sitemapjekyll-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 写对。

根据以上的分析,可以得出以下几个结论:

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

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

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

05-11 17:23