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 build 或 jekyll 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 或更早版本创建，也许会在运行 serve 或 build 时收到下述错误：

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。

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