从2.x版本升级到3.x版本

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

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

gem update jekyll

Since version 3.2 , Jekyll requires Ruby version >= 2.1.

site.collections的变化

在 2.x 版本中，对 site.collections 的循环访问返回的是一个具有两个项目的数组，首个项目是集合名称（label），而第二个项目是集合对象。在 3.x 版本中，我们移除这个复杂的访问方式，在每一次循环迭代中返回的都只是一个简单的集合对象。

在你的模板中需要中如下的简单转化：

• collection[0] becomes collection.label
• collection[1] becomes collection

在循环访问 site.collections 时，记得进行上述转换。

对于 Jekyll 2 中的 site.collections.myCollection，现在你需要：

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

起初这看起来有一点繁琐，但这总比一个庞大的for循环要好。

Textile support

We dropped native support for Textile, from now on you have to install our jekyll-textile-converter plugin to work with Textile files.

移除依赖项

我们的核心团队移除了一些可选的依赖项。在 3.0 中，如果你使用到了相关特性，你需要额外安装并包含进来。这些依赖项包括：

• jekyll-paginate – Jekyll的日志分页系统
• jekyll-coffeescript – CoffeeScript 处理器
• jekyll-gist – gist Liquid 标签
• pygments.rb – Pygments 高亮支持
• redcarpet – Markdown 处理器
• toml – YAML 配置文件的替代品
• classifier-reborn – 处理 site.related_posts

未来文章

A seeming feature regression in 2.x, the --future flag was automatically enabled. The future flag allows post authors to give the post a date in the future and to have it excluded from the build until the system time is equal or after the post time. In Jekyll 3, this has been corrected. Now, --future is disabled by default. This means you will need to include --future if you want your future-dated posts to generate when running jekyll build or jekyll serve.

Layout metadata

Introducing: layout. In Jekyll 2 and below, any metadata in the layout was merged onto the page variable in Liquid. This caused a lot of confusion in the way the data was merged and some unexpected behaviour. In Jekyll 3, all layout data is accessible via layout in Liquid. For example, if your layout has class: my-layout in its front matter, then the layout can access that via {{ layout.class }}.

Syntax highlighter changed

For the first time, the default syntax highlighter has changed for the highlight tag and for backtick code blocks. Instead of Pygments.rb, it’s now Rouge. If you were using the highlight tag with certain options, such as hl_lines, they may not be available when using Rouge. To go back to using Pygments, set highlighter: pygments in your _config.yml file and run gem install pygments.rb or add gem "pygments.rb" to your project’s Gemfile.

Relative Permalink support removed

In Jekyll 3 and above, relative permalinks have been deprecated. If you created your site using Jekyll 2 and below, you may receive the following error when trying to serve or 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.

This can be fixed by removing the following line from your _config.yml file:

relative_permalinks: true

Permalinks no longer automatically add a trailing slash

In Jekyll 2, any URL constructed from the permalink: field had a trailing slash (/) added to it automatically. Jekyll 3 no longer adds a trailing slash automatically to permalink: URLs. This can potentially result in old links to pages returning a 404 error. For example, suppose a page previously contained the YAML permalink: /:year-:month-:day-:title that resulted in the URL example.com/2016-02-01-test/ (notice the trailing slash), Jekyll internally generates a folder named 2016-02-01-test. In Jekyll 3, the same permalink: generate the file 2016-02-01-test.html and the URL for the same page will be example.com/2016-02-01-test, and consequently any links to the old URL will result in a 404 error. In order to maintain the same URLs and avoid this problem, a trailing slash should be added to the permalink: field, for example permalink: /:year-:month-:day-:title/.

All my posts are gone! Where’d they go!

Try adding future: true to your _config.yml file. Are they showing up now? If they are, then you were ensnared by an issue with the way Ruby parses times. Each of your posts is being read in a different timezone than you might expect and, when compared to the computer’s current time, is “in the future.” The fix for this is to add a timezone offset to each post (and make sure you remove future: true from your _config.yml file). If you’re writing from California, for example, you would change this:

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

to this (note the offset):

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

My categories have stopped working!

If you organized your categories as /_posts/code/2008-12-24-closures.md, you will need to restructure your directories to put the categories above the _posts directories, as follows: /code/_posts/2008-12-24-closures.md.

Did we miss something? Please click “Improve this page” above and add a section. Thanks!