Jekyll 从 2.x 升级到 3.x 注意事项

从旧版本升级到 Jekyll？Jekyll 3 中有一些变化需要你特别注意。

在开始之前，先获取最新版本的 Jekyll：

gem update jekyll

从 3.2 版本开始，Jekyll 要求 Ruby 版本 >= 2.1。

快速开始

想快速创建并运行一个新的 Jekyll 网站？只需执行 jekyll new SITENAME，即可创建一个包含基础结构的 Jekyll 网站目录。

site.collections 已发生变化

在 2.x 中，遍历 site.collections 时，返回的是一个数组，其中第一个元素是集合标签（label），第二个元素是集合对象。在 3.x 中，这种复杂结构已被移除，现在遍历时直接返回集合对象本身。

因此，你需要在模板中进行以下简单转换：

在遍历 site.collections 时，请确保完成上述修改。

在 Jekyll 2 中使用 site.collections.myCollection 的方式，现在需要改为：

{% assign myCollection = site.collections | where: "label", "myCollection" | first %}

虽然一开始会觉得有点麻烦，但比写一个大型 for 循环更简单。

Textile 支持

我们移除了对 Textile 的原生支持。现在如果你想继续使用 Textile 文件，需要安装 jekyll-textile-converter 插件。

移除的依赖项

我们移除了一些核心团队认为属于可选功能的依赖。因此在 Jekyll 3.0 中，如果你需要使用相关功能，必须手动安装并显式引入这些依赖。

包括：

未来文章

在 2.x 中，有一个看似功能回退的问题：--future 参数默认是 开启 的。

future 参数允许文章作者设置未来时间的发布日期，并在系统时间达到该时间之前，不将文章生成到网站中。

在 Jekyll 3 中，这个问题已经被修复。现在，--future 默认是关闭的。

这意味着，如果你希望在执行 jekyll build 或 jekyll serve 时生成未来日期的文章，需要手动添加 --future 参数。

GitHub Pages 中的未来文章

上述规则有一个例外：GitHub Pages 网站中的 --future 参数默认仍然保持 开启， 以维持历史兼容性。

布局元数据

新增：layout。

在 Jekyll 2 及更早版本中，布局文件中的元数据会被合并到 Liquid 的 page 变量中。这导致数据合并逻辑容易让人困惑，也会出现一些意料之外的行为。

在 Jekyll 3 中，所有布局数据现在都通过 Liquid 中的 layout 变量访问。

例如，如果你的布局 Front matter 中包含：

class: my-layout

那么可以通过 {{ layout.class }} 来访问。

语法高亮器更改

这是首次默认代码高亮器发生变化。

用于 highlight 标签和反引号代码块的默认高亮器，已从 Pygments.rb 更换为 Rouge。

如果你之前在 highlight 标签中使用了一些特殊选项（例如 hl_lines），这些选项在 Rouge 中可能不可用。

如果你想继续使用 Pygments，请在 _config.yml 中设置：

highlighter: pygments

然后执行：

gem install pygments.rb

或者在项目的 Gemfile 中添加：

gem "pygments.rb"

在 Jekyll 3 及以上版本中，相对永久链接（relative permalinks）已被废弃。

如果你的网站是基于 Jekyll 2 或更早版本创建的，在执行 serve 或 build 时，可能会看到以下错误：

Since v3.0, permalinks for pages in subfolders must be relative to the site
source directory, not the parent directory. Check
https://jekyllrb.com/docs/upgrading/ for more info.

解决方法是从 _config.yml 中删除以下配置：

relative_permalinks: true

在 Jekyll 2 中，任何通过 permalink: 生成的 URL，都会自动追加尾部斜杠（/）。

而在 Jekyll 3 中，permalink: 不再自动添加尾部斜杠。

这可能会导致旧链接返回 404 错误。

例如，之前页面中配置：

permalink: /:year-:month-:day-:title

最终生成的 URL 为：

example.com/2016-02-01-test/

（注意最后的斜杠）

Jekyll 内部会生成一个名为 2016-02-01-test 的目录。

但在 Jekyll 3 中，相同配置会生成：

2016-02-01-test.html

页面 URL 也会变成：

example.com/2016-02-01-test

因此，旧链接会出现 404。

为了保持原有 URL 不变并避免该问题，你需要在 permalink: 后手动添加尾部斜杠，例如：

permalink: /:year-:month-:day-:title/

我的所有文章都不见了！它们去哪了！

尝试在 _config.yml 中添加：

future: true

现在文章是否恢复显示了？

如果恢复了，那么你遇到的是 Ruby 时间解析方式导致的问题。

你的文章被解析到了一个与你预期不同的时区中，因此与当前系统时间比较时，被认为“属于未来时间”。

解决方法是为每篇文章添加时区偏移量（timezone offset），并确保随后从 _config.yml 中删除 future: true。

例如，如果你在加利福尼亚写文章，原本：

---
date: 2016-02-06 19:32:10
---

应改为（注意时区偏移）：

---
date: 2016-02-06 19:32:10 -0800
---

我的分类不再起作用了！

如果你之前将分类目录组织为：

/_posts/code/2008-12-24-closures.md

现在需要调整目录结构，把分类目录放到 _posts 目录上层，例如：

/code/_posts/2008-12-24-closures.md

我们遗漏了什么吗？请点击上方的 “Improve this page” 添加内容。感谢支持！