GitHub Pages 与 Gitee Pages 上的 Jekyll
<blockquote class="alert-transfer">本文已不再于此更新，最新版本请见：xjtu-blacksmith.cn/essay/jekyll-of-pages。
</blockquote>
<p></p><div class="toc"><div class="toc-container-header">目录</div><ul><li>Jekyll on GitHub Pages<ul><li>Jekyll 的 Markdown 引擎</li><li>常规插件</li><li>静默增强插件</li><li>GitHub Pages 主题</li><li>总结</li></ul></li><li>Jekyll on Gitee Pages</li></ul></div><p></p>
<p>GitHub 与 Gitee 提供的 Pages 服务中，均内嵌了 Jekyll 支持（Gitee 还提供了 Hugo 与 Hexo 支持）。所谓「支持」，即指这些生成工具挂在云端；你只需要提供原始代码（如 Markdown 文档、Sass/Stylus/Less 样式表），再由 Pages 服务自动编译、部署即可。这样，搭建网站的技术门槛进一步下降，你只需要会两件事就能搭建网站了：</p>
<ol>
<li>会写 Markdown 文档；</li>
<li>注册 GitHub 或 Gitee 账号，点点鼠标，在你的代码仓库中启用 Pages 服务。</li>
</ol>
<p>因为技术门槛如此之低，导致不少用户压根就意识不到 Pages 服务内置了 Jekyll 工具，甚至以为每一个 Markdown 文档理所当然地就能变成一个网页。此外，另一个常被忽视的问题是：由 Pages 服务调用的 Jekyll 工具，并非最新版本，而且隐性地增添了许多插件，这可能使用户在本地使用 Jekyll 或迁移平台时碰上「不协调」的问题。最常见的一个问题就是：在 GitHub Pages 上正常生成的代码仓库，到 Gitee Pages 上就变得一团糟。这不是因为 Gitee Pages 的功能「不如」GitHub Pages，而是因为：</p>
<blockquote>
<p>GitHub Pages 没有告诉你它们为自己的 Jekyll 多加了几个插件，Gitee Pages 也没有告诉你它们的 Jekyll 并没有这些插件。</p>
</blockquote>
<p>这里对 GitHub Pages 与 Gitee Pages 所使用的 Jekyll 进行一个简单的分析（后面姑且简称为 GitHub Jekyll 与 Gitee Jekyll），以说明它们隐性地附加了哪些功能，需要特别注意。</p>
<h2 id="jekyll-on-github-pages">Jekyll on GitHub Pages</h2>
<p>GitHub Pages 中所采用的 Jekyll 及插件、依赖，被汇总到名为 <code>github-pages</code> 的 Gem 中（主页）。如果你在本地安装了这个 Gem，可以运行它来查看其所要求的各项依赖版本。以目前最新的 <code>204</code> 版本为例，在 shell 中运行：</p>
<pre><code class="language-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 |
+------------------------------+---------+
</code></pre>
<p>能看到其列出来一大串的 Gem。通过这个页面也可以看到 GitHub Pages 上的 Jekyll 版本及相关依赖。</p>
<p>以上这些 Gem，可以大致划分为四类：</p>
<ol>
<li>Jekyll 及其依赖，比如 Sass 转换、Kramdown 引擎、Liquid 模板语言、Rouge 高亮器等等。这些算是常规构件，不可或缺。注意，目前 GitHub Pages 使用的 Jekyll 版本为 3.8.5，而最新版本是 4.0.0，有一个「适当」的延迟。</li>
<li>为 GitHub Pages 定制的额外功能，主要有两个：<code>jekyll-commonmark-ghpages</code>，在 Commonmark 基础上改出来的 GFM 引擎（但 Jekyll 仍然默认用 Kramdown）；<code>github-pages-health-check</code>，用于检查域名（DNS 服务）和 GitHub Pages 服务是否正常。</li>
<li>若干 Jekyll 插件，基本上都是 <code>jekyll</code> 开头。后面会详细分析。</li>
<li>若干 Jekyll 主题，除了 Jekyll 的默认主题 <code>minima</code> 和一个基本主题 <code>jekyll-swiss</code> 之外，还有 13 个 <code>jekyll-theme</code> 开头的，它们就是你在 GitHub Pages 服务里即选即用的 13 个主题。</li>
</ol>
<p>从以上后三类可以看到，GitHub Jekyll 其实「加持」了很多的辅助件，并不单纯。而这样多的辅助构件，最终营造出了前面所提的「每一个 Markdown 文档理所当然地可以变成一个网页」之幻觉。事实上，如果是纯粹用 Jekyll 搭建网站，所需要做的工作仍然是不少的。</p>
<p>下面再详细分析一下 GitHub Jekyll 所采用的插件。</p>
<h3 id="jekyll-的-markdown-引擎">Jekyll 的 Markdown 引擎</h3>
<p>在 Maruku 停止更新后，Jekyll 的默认 Markdown 引擎变成了 Kramdown，同样也是一个用 Ruby 开发的工具。Kramdown 实现了相当多的拓展功能，典型者如 LaTeX 公式、行内属性标记等，拓展了用 Markdown 实现网页（HTML）的可能性。</p>
<p>GitHub Jekyll 也是默认用 Kramdown 渲染 Markdown，不过前面看到其也提供了一个 GFM 引擎。在 GitHub 的官方文档中对此有特别说明，并强调「只有使用后者才能保证网站效果与 GitHub 中（渲染的 Markdown 页面）的一样」。仔细想想，有这个需求的用户应该不在少数。</p>
<h3 id="常规插件">常规插件</h3>
<p>在 GitHub Jekyll 所用插件之中，下面这些是比较常规、常见的（强调者表示默认启用）：</p>
<ul>
<li><code>jekyll-sitemap</code>，用于生成站点地图文件 <code>sitemap.xml</code> 供搜索引擎抓取；</li>
<li><code>jekyll-feed</code>，用于生成 RSS 订阅链接 <code>feed.xml</code>；</li>
<li><code>jekyll-coffeescript</code>，CoffeeScript 转换器；</li>
<li><code>jekyll-redirect-from</code>，重定向插件，从功能上可以理解为 <code>permalink</code> 的反面；</li>
<li><em><code>jekyll-paginate</code></em>，分页器；</li>
<li><code>jemoji</code>，表情包；</li>
<li><code>jekyll-avatar</code>，提供了形如 <code>{% avatar %}</code> 的标签，用于获取 GitHub 用户的头像；</li>
<li><code>jekyll-remote-theme</code>，使你能够使用挂在 GitHub 上的 Jekyll 主题；</li>
<li><code>jekyll-gist</code>，提供了形如 <code>{% gist xxx %}</code> 的标签，用于在页面上展示 Gist 的内容；</li>
<li><code>jekyll-mentions</code>，使得 GitHub 上的 <code>@</code> 用户功能在网站中得到支持；</li>
<li><code>jekyll-relative-links</code>，能够将指向 Markdown 文档的链接转换为指向对应 HTML 页面的链接（有点鸡肋）。</li>
</ul>
<p>其中许多算是 Jekyll 的标配插件，经常被使用。它们更多地是提供了一种可选项，不会对网站的生成效果有太大影响。</p>
<h3 id="静默增强插件">静默增强插件</h3>
<p>除了上面所提的基本插件，另外的插件则非常「阴险」，默认启用，发挥了一些你根本意识不到的功能。包括：</p>
<ul>
<li><code>jekyll-seo-tag</code>：定制了 <code>{% seo %}</code> 这个 Liquid 标签的功能。SEO 的其他方面不说，网站的 <code><title></code> 元素就是它搞定的（使用了 <code>_configs.yml</code> 文件中的 <code>title</code> 和 <code>description</code> 属性）。所以在用 GitHub Jekyll 时要想改变网页标题的格式，就必须要求它停止输出标题：<code>{% seo title=false %}</code>，否则你会以为标题是「无中生有」的。</li>
<li><code>jekyll-github-metadata</code>：用于从 GitHub 获取元信息，比如项目名称、作者之类的。它主要是给 GitHub Pages 生成的网站提供一些默认参数，比如上面的 SEO 插件就会使用 GitHub 仓库的项目名称、描述作为网站的标题和副标题。在本地用 Jekyll 构建 Pages 上的网站时，十有八九会出现「<em>No GitHub API authentication</em>」的警告，这个锅也得由它来背（它要用 GitHub API 来获取这些信息）。</li>
<li><code>jekyll-optional-front-matter</code>：根据 Jekyll 的机制，其只会转换有 YAML 头信息（哪怕是空的）的 Markdown 文件，这个插件则取消了这一要求。所以如果你发现用在其他场合使用 Jekyll 时许多 Markdown 文件没有被转换，你会意识到这个插件的作用：让你不用写头信息。（另外，这个规则对 Sass 文件不使用，所以你得对自己写的、放在 <code>_sass</code> 目录以外的 Sass 文件至少给一个空的头信息。）</li>
<li><code>jekyll-readme-index</code>：这个插件使得 Jekyll 在找不到 <code>index.html</code> 或 <code>index.md</code> 时，将 <code>README.md</code> 转换为 <code>index.html</code> 作为替代。这个功能的好处在于实现了 GitHub 页面预览和网站构建的统一，因为在 GitHub 页面上 <code>README</code> 的作用就相当于一般网站的 <code>index.html</code>。</li>
<li><code>jekyll-default-layout</code>：帮助你自动给首页套 <code>layout: home</code>、给推送文章套 <code>layout: post</code>、给一般页面套 <code>layout: page</code>、实在不行就套 <code>layout: default</code>。作用很明显：让你不用写头信息。</li>
<li><code>jekyll-titles-from-headings</code>：自动将一个没有指明 <code>title</code> 的 Markdown 文件之首级标题提取为 <code>title</code>。从页面显示来说，一个页面有没有 <code>title</code> 其实无关紧要，但需要生成网站导航、文章列表等的时候就必须确保每个页面都有 <code>title</code>。这个功能的作用也很明显：让你不用写头信息。</li>
</ul>
<p>以上几个插件，都是「静默」生效；其中不少在 Jekyll 中并不默认启用，但它们在 GitHub Jekyll 中全都是默认启用的。它们发挥的作用，也许你之前从未意识到，但现在一看即知。</p>
<h3 id="github-pages-主题">GitHub Pages 主题</h3>
<p>GitHub Pages 提供的 13 个基本主题，也被包含在依赖当中，这意味着你不需要安装就能使用它们。它们在 <code>_configs.yml</code> 中用 <code>theme</code> 属性启用（也许这是许多人见过的第一行 YAML 代码？），这会给初学者造成一种误解，以为其他的主题也可以这样通过一行代码来使用。</p>
<p>事实上，如果要在 GitHub Jekyll 中使用其他主题，有这样两种办法：</p>
<ol>
<li>启用 <code>jekyll-remote-theme</code> 插件，这样你就可以使用任意一个在 GitHub 上公开的 Jekyll 主题（其他地方的不行）；</li>
<li>把主题下载下来，将对应文件拷贝到指定位置——注意清理之前的主题。（Jekyll 的主题管理不是很灵活，不如 Hugo、Hexo 等工具。）</li>
</ol>
<p>当然，如果你是在本地生成网站文件后再借 Pages 的服务器发布，方法就比较多了。</p>
<h3 id="总结">总结</h3>
<p>经过以上对各个依赖的分析，我们可以发现：GitHub Jekyll 提供了相当多的辅助功能，极大的化简了网站的生成，而我们甚至还不自知。在不清楚这些背景的情况下，尝试从 GitHub Pages 服务下迁移出 Jekyll 项目，很有可能会踩坑，比如：</p>
<ul>
<li>为什么这个 Markdown 文件没有被转换？（因为你没有写头文件，怪 <code>jekyll-optional-front-matter</code>）</li>
<li>为什么文章列表里的文章标题都是空的？（因为它们的标题是正文中的 <code>h1</code> 标签，没有写到头信息中的 <code>title</code> 里，怪 <code>jekyll-titles-from-headings</code>）</li>
<li>为什么这个路径下的页面不见了？（因为你原来用的是 <code>README.md</code> 转换成 <code>index.html</code>，怪 <code>jekyll-readme-index</code>）</li>
</ul>
<p>当然，问题的可能性不多，一一排除总能解决。所以归结出一个结论：与其花时间琢磨上面这么多 Gem 的关系，还不如自己去踩踩坑。</p>
<p>坑归坑，好话也还是要说几句：如果只是一直用 GitHub Jekyll，以上这些都不算是问题，而算优势。「Markdown 文件自动变成网页」这样的好事，还是人人所欲的；它毕竟能让许多完全不了解前端技术的人构建一整个网站出来，应该算是大好事。</p>
<h2 id="jekyll-on-gitee-pages">Jekyll on Gitee Pages</h2>
<p>Gitee Pages 究竟用的是绿 Jekyll 还是花 Jekyll，没有公开信息，只能间接地寻找一些蛛丝马迹了。</p>
<p>尝试在一个 Gitee 仓库中启用了 Gitee Pages，发现它支持 <code>jekyll-seo-tag</code>，但在生成的 HTML 页面上赫然显示该插件版本为 <code>2.3.0</code>。经过检查，这个版本是 2017 年八月发布的，看来有些年头了。</p>
<p>但是仅从这一个插件不能推断出所有信息。为此，我又测试了其他几个插件，发现：</p>
<ul>
<li><code>jekyll-sitemap</code>、<code>jekyll-feed</code> 两个插件都可以正常使用，说明它们算是 Gitee Jekyll 的依赖。</li>
<li>另外，在 <code>jekyll-feed</code> 生成的 <code>feed.xml</code> 中意外发现了 Jekyll 的版本信息：<code>3.6.2</code>。检查发现这是 2017 年十月发布的版本。</li>
<li><code>jekyll-mentions</code> 插件竟然可以用，指向 GitHub 的用户主页——自己做一个 Gitee 版本的应该也挺容易吧？跟 GitHub 有什么关系？</li>
<li><code>jemoji</code> 用不了。</li>
<li>几个静默强化插件中，除了 <code>jekyll-github-metadata</code> 未启用之外，其他的都能正常工作。这造成的后果是，在 Gitee Pages 中必须自己写 <code>baseurl</code>，否则站点的样式表就找不着了，链接也会错乱。</li>
<li><code>jekyll-remote-theme</code> 居然能用……前提是把 <code>baseurl</code> 写对。</li>
</ul>
<p>根据以上的分析，可以得出以下几个结论：</p>
<ol>
<li>Gitee Jekyll 的版本很旧了，一整套工具可能只是 2017 年末的「最新版」。找到了 Gitee Pages 的上线说明，发布时间是在 2018 年年中，差不太远（也许前端支持做好之后半年在做后端支持）。</li>
<li>Gitee Jekyll 跟 GitHub Jekyll 对接不良，迁移或同步的话得增补很多信息，并且不少插件用不了。</li>
<li>Gitee Jekyll 竟然支持 GitHub 上的远程主题，但是用起来似乎也存在若干问题，不稳定。</li>
</ol>
<p>以上三条再归纳为一个最终的结论：<em>（目前的）Gitee Jekyll 不可靠</em>。为了用 Gitee Pages，只有在本地生成网站文件再发布了。和 GitHub Pages 比起来，这无疑抬高了使用门槛；这倒不算什么，重要的是在这种情况下 Gitee Jekyll 形同虚设，不会有什么人去用了。</p>
<p>冷嘲热讽不能解决问题。刚刚和 Gitee 管理团队联系上，表示将来会改进这些问题。持续关注。如果 Gitee Pages 的生态做出来了，肯定是也是一件大好事吧！</p>
</div>
<div id="MySignature" role="contentinfo">
<p><strong>本博客上不以【校理】字样作为标题的文章，其著作权均归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。</strong></p><p>
</p><p>本人为西安交通大学能动学院本科生，欢迎对相关内容提出批评与建议！</p>
<p>Github个人主页：https://github.com/xjtu-blacksmith/</p>
<p>欢迎关注西安交大钱院学辅信息站：https://qyxf.site/</p>
<p>邮箱：yjr134@163.com</p><br><br>
来源：https://www.cnblogs.com/xjtu-blacksmith/p/jekyll-of-pages.html
頁:
[1]