改善此页面

从 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 的迭代会产生一个数组，其中集合标签和集合对象分别作为第一个和第二个项目。在 3.x 中，此复杂性已被移除，迭代现在仅产生集合对象。必须在模板中进行简单的转换

  • collection[0] 变为 collection.label
  • collection[1] 变为 collection

在对 site.collections 进行迭代时，确保进行了上述转换。

对于 Jekyll 2 中的 site.collections.myCollection，你现在可以执行以下操作

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

这起初有点繁琐，但比一个大的 for 循环要容易。

Textile 支持

我们取消了对 Textile 的本机支持，从现在开始，你必须安装我们的 jekyll-textile-converter 插件才能使用 Textile 文件。

取消的依赖项

我们取消了一些核心团队认为是可选的依赖项。因此，在 3.0 中，如果你使用任何功能，则必须明确安装并包含这些依赖项。它们是

  • jekyll-paginate – Jekyll 过去的分页解决方案
  • jekyll-coffeescript – 处理 CoffeeScript
  • jekyll-gist – gist Liquid 标记
  • pygments.rb – Pygments 高亮显示器
  • redcarpet – Markdown 处理器
  • toml – YAML 的配置文件替代方案
  • classifier-reborn – 适用于 site.related_posts

未来帖子

2.x 中的一个看似功能退步的 --future 标记被自动启用。未来标记允许帖子作者在未来给帖子一个日期，并在系统时间等于或晚于帖子时间之前将其排除在构建之外。在 Jekyll 3 中，此问题已得到纠正。现在，--future 默认情况下处于禁用状态。这意味着如果你希望在运行 jekyll build 或 jekyll serve 时生成未来日期的帖子，则需要包含 --future。

GitHub Pages 上的未来帖子

上述规则的一个例外是 GitHub Pages 网站，其中 --future 标记默认保持启用，以保持这些网站的历史一致性。

布局元数据

介绍：layout。在 Jekyll 2 及更低版本中，布局中的任何元数据都会合并到 Liquid 中的 page 变量上。这导致数据合并方式出现很多混乱，并出现一些意外的行为。在 Jekyll 3 中，所有布局数据都可以通过 Liquid 中的 layout 访问。例如，如果你的布局在其前端内容中有 class: my-layout，那么布局可以通过 {{ layout.class }} 访问它。

语法高亮显示器已更改

对于 highlight 标记和反引号代码块，默认语法高亮显示器首次发生更改。它现在是 Rouge，而不是 Pygments.rb。如果你使用 highlight 标记和某些选项，例如 hl_lines，则在使用 Rouge 时可能无法使用这些选项。要恢复使用 Pygments，请在 _config.yml 文件中设置 highlighter: pygments 并运行 gem install pygments.rb 或将 gem "pygments.rb" 添加到项目的 Gemfile 中。

在 Jekyll 3 及更高版本中，相对永久链接已被弃用。如果你使用 Jekyll 2 及更低版本创建了你的网站，则在尝试提供服务或构建时可能会收到以下错误

Since v3.0, permalinks for pages in subfolders must be relative to the site
source directory, not the parent directory. Check
https://jekyll.ruby-lang.org.cn/docs/upgrading/ for more info.

可以通过从你的 _config.yml 文件中移除以下行来修复此错误

relative_permalinks: true

在 Jekyll 2 中，从 permalink: 字段构建的任何 URL 都会自动添加一个尾部斜杠 (/)。Jekyll 3 不再自动向 permalink: URL 添加尾部斜杠。这可能会导致指向页面的旧链接返回 404 错误。例如，假设一个页面之前包含 YAML permalink: /:year-:month-:day-:title，导致 URL 为 example.com/2016-02-01-test/（注意尾部斜杠），Jekyll 在内部生成一个名为 2016-02-01-test 的文件夹。在 Jekyll 3 中，相同的 permalink: 会生成文件 2016-02-01-test.html，并且同一页面的 URL 将为 example.com/2016-02-01-test，因此指向旧 URL 的任何链接都会导致 404 错误。为了保持相同的 URL 并避免此问题，应向 permalink: 字段添加一个尾部斜杠，例如 permalink: /:year-:month-:day-:title/。

我的所有帖子都不见了！它们去哪儿了！

尝试向你的 _config.yml 文件添加 future: true。它们现在显示了吗？如果显示了，那么你遇到了 Ruby 解析时间的方式存在的问题。你的每个帖子都在你可能预料之外的时区中被读取，并且在与计算机当前时间比较时，“在未来”。解决此问题的方法是向每个帖子添加 时区偏移（并确保从你的 _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。

我们是否遗漏了一些内容？请点击上方的“改进此页面”并添加一个部分。谢谢！