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
。
我们漏掉了什么吗?点击页面上方的“发现错误或贡献翻译”来新增章节