Jekyll项目升级指南：从2.x版本迁移到3.x版本

Jekyll项目升级指南：从2.x版本迁移到3.x版本

jekyll :globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby 项目地址: https://gitcode.com/gh_mirrors/je/jekyll

前言

作为一款流行的静态网站生成器，Jekyll在3.x版本中引入了一些重大变更。本文将详细解析这些变化，帮助开发者顺利完成版本迁移。我们将从环境要求、功能变更到具体配置调整，全面覆盖升级过程中可能遇到的各类问题。

环境准备

在开始升级前，请确保您的系统满足以下要求：

1. 执行以下命令获取最新版Jekyll：

gem update jekyll

2. 版本要求：

• 自3.2版本起，Jekyll要求Ruby版本≥2.1

核心变更解析

1. 集合(Collections)接口变更

旧版行为： 在2.x版本中，迭代site.collections会返回一个数组，其中第一个元素是集合标签，第二个元素是集合对象。

新版变化： 3.x版本简化了这一设计，直接返回集合对象。

迁移方案：

• 将collection[0]替换为collection.label
• 将collection[1]替换为collection

对于特定集合的访问，现在需要使用Liquid过滤器：

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

2. 文本处理相关变更

Textile支持： 3.x版本移除了对Textile的原生支持。如需继续使用，需单独安装jekyll-textile-converter插件。

Markdown处理器： 默认的语法高亮器从Pygments.rb变更为Rouge。如需继续使用Pygments：

1. 在配置文件中设置：

highlighter: pygments

2. 安装依赖：

gem install pygments.rb

3. 依赖项调整

3.x版本将以下功能移出核心包，需要单独安装：

• 分页功能(jekyll-paginate)
• CoffeeScript处理(jekyll-coffeescript)
• Gist标签支持(jekyll-gist)
• TOML配置支持(toml)
• 相关文章功能(classifier-reborn)

重要功能变更

1. 未来文章处理

行为变更：

• 2.x版本默认启用--future选项
• 3.x版本默认禁用该选项

影响： 未来日期的文章默认不会生成，需显式指定--future参数。

解决方案：

• 构建命令中添加参数：jekyll build --future
• 或在配置文件中设置：future: true

2. 布局元数据访问

旧版问题： 布局中的元数据会合并到page变量，导致意外行为。

新版改进： 布局元数据现在通过独立的layout变量访问。

示例： 布局中定义：

class: my-layout

模板中访问：

{{ layout.class }}

3. 永久链接(Permalink)调整

重大变更：

• 移除了相对永久链接支持
• 不再自动添加尾部斜杠

迁移方案：

1. 删除配置文件中的：

relative_permalinks: true

2. 如需保留尾部斜杠，需显式指定：

permalink: /:year-:month-:day-:title/

常见问题解决方案

文章消失问题

现象：升级后文章无法显示。

可能原因：时区解析问题导致文章被识别为"未来文章"。

解决方案：

1. 为每篇文章添加时区偏移：

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

2. 避免在配置中设置future: true

分类目录失效

目录结构调整： 从：

/_posts/code/2008-12-24-closures.md

改为：

/code/_posts/2008-12-24-closures.md

总结

Jekyll 3.x版本通过精简核心功能、优化API设计，提供了更加清晰和可维护的架构。虽然升级过程可能需要一些调整，但这些变更最终将带来更好的开发体验。建议开发者在升级前充分测试，特别是检查永久链接和分类结构等关键功能。

jekyll :globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby 项目地址: https://gitcode.com/gh_mirrors/je/jekyll