Upgrading from 2.x to 3.x

打算升级旧版本Jekyll?那么在3.0版本中有一些变化,您需要首先了解一下。

在我们开始动手之前,请先获取最新版本的 Jekyll:

$ gem update jekyll

注意:安装Jekyll 3需要 >= 2.0.0 版本的Ruby。

立即开始

想快速构建并运行一个全新的 Jekyll 站点吗?只需要执行 jekyll new SITENAME 就可以轻松创建一个包括了Jekyll网站框架的文件夹。

site.collections 不再是数组

在 2.x 版本中,对 site.collections 的循环访问返回的是一个具有两个项目的数组,首个项目是集合名称(label),而第二个项目是集合对象。 在 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 循环要好。

移除依赖项

我们的核心团队移除了一些可选的依赖项。在 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 版本的特性回退。在 2.x 版本中未来文章 --future 默认开启(enabled)。 未来(future)标记允许作者设定一个未来的时间,在到达该时间点之前,网站构建时会将相关文章排除在外。 在 Jekyll 3 中,这项设置进行了修正。 现在, --future 默认为禁用。 这意味着如果你想在未来发布某篇文章,你需要在生成站点运行 jekyll buildjekyll serve 时手动添加 --future 标记。

布局元数据

引入布局 layout。在 Jekyll 2 及之前的版本中,所有关于布局的元数据都写在了 Liquid 模板的 page 变量中。这在数据合并的时候导致了困扰,同时也造成了一些不可预期的行为。 在 Jekyll 3 中,所有的布局数据都可以通过 Liquid 中的 layout 进行访问。 例如在 YAML 头信息中,你的布局数据有 class: my-layout 这一项, 那么就可以通过 {{ layout.class }} 来访问相关数据。

语法高亮

这是我们首次对 highlight 标签和撇号代码块进行改变。我们从 Pygments.rb 改到了 Rouge。如果你使用了带有选项的 highlight 标签, 例如 hl_lines,在使用 Rouge 的新版本中,这些选项不再有效。 想要继续使用 Pygments,在_config.yml 中设置 highlighter: pygments并运行 gem install pygments.rb 即可,或者将 gem 'pygments.rb' 添加到项目的 Gemfile 中。

不再支持永久相对链接

在 Jekyll 3 及更高版本中,我们弃用了永久相对链接。 如果你的网站用 Jekyll 2 或更早版本创建,也许会在运行 servebuild 时收到下述错误:

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

移除项目 _config.yml 文件中的下面一行可以解决这个问题:

relative_permalinks: true

永久链接不再自动添加斜杠

在 Jekyll 2 中,用 permalink: 域生成的永久链接会自动添加斜杠 (/) 。Jekyll 3 不再自动为链接添加斜杠。 这有可能会造成旧链接返回 404 错误。例如,此前有一个页面的 YAML 包含永久链接设置 permalink: /:year-:month-:day-:title, 生成的永久链接是 example.com/2016-02-01-test/ (注意结尾的斜杠),Jekyll 会生成一个名叫 2016-02-01-test 的文件夹。 在 Jekyll 3中,同样的 permalink: 会生成一个名叫 2016-02-01-test.html 的文件,同一个页面的链接会变成 example.com/2016-02-01-test。 这就会导致旧的链接无法找到相应的页面。 为了使用相同的链接而避免找不到页面的问题,在 permalink: 设置中,应当添加斜杠,例如设置为 permalink: /:year-:month-:day-:title/

我的文章不见了!它们去哪儿了!

试试在 _config.yml 文件中添加 future: true,它们现在出现了吗?如果它们出现了,这就是因为 Ruby 在处理时间时候的问题。 你的每篇文章被放在了不同的时区之下,在和本地计算机时间对比的时候,就都是“未来”文章。为了修正这个问题,可以为每篇文章设置一个 [时区偏移](https://www.wikiwand.com/zh/%E6%97%B6%E5%8C%BA%E5%88%97%E8%A1%A8)(并且确保你从 _config.yml 中移除了 future: true)。 举例来说,如果你在北京写作,你需要更改下面的内容:

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

改成(注意时区偏移 +0800):

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

我的分类坏掉了!

如果你用 /_posts/code/2008-12-24-closures.md 这样的方式来进行分类,你需要重新构建目录,把类别目录放在 _posts 之外,也就是说改为:/code/_posts/2008-12-24-closures.md

我们漏掉了什么吗?点击页面上方的“发现错误或贡献翻译”来新增章节

此网站由 @xcatliu 维护,由 开源爱好者们 共同翻译。若发现错误或想贡献翻译,请访问: xcatliu/jekyllCN