Jekyll 4.0 升级指南：从 3.x 迁移到 4.x 的关键变化

Jekyll 4.0 升级指南：从 3.x 迁移到 4.x 的关键变化

jekyll 项目地址: https://gitcode.com/gh_mirrors/jek/jekyll

前言

Jekyll 4.0 带来了一系列重要的改进和变化，这些变化旨在提升构建性能并简化开发体验。本文将详细介绍从 Jekyll 3.x 升级到 4.x 版本时需要注意的关键变更点，帮助开发者顺利完成迁移。

环境准备

在开始升级前，请确保你的 Ruby 版本满足最低要求。Jekyll 4.0 需要 Ruby {{ site.data.ruby.min_version }} 或更高版本。可以通过以下命令检查当前 Ruby 版本：

ruby -v

如果版本符合要求，可以通过以下命令更新 Jekyll：

gem update jekyll

重要变更点

1. post_url 标签行为变化

Jekyll 4.0 对 post_url 标签进行了重要改进，现在它会自动处理 baseurl 前缀。这意味着你不再需要手动添加 {{ site.baseurl }}。

修改前：

{{ site.baseurl }}{% post_url 2018-03-20-hello-world.markdown %}

修改后：

{% post_url 2018-03-20-hello-world.markdown %}

2. 模板渲染机制优化

Jekyll 4.0 改进了模板解析和渲染流程：

1. 模板现在只会被解析一次并缓存
2. 缓存的模板会根据需要被多次渲染
3. 这种变化显著提升了构建速度

影响范围：

• 某些社区插件可能需要调整以适应新的渲染机制
• 依赖旧渲染行为的自定义插件可能需要重写

3. 静态文件处理规则变化

对于非 posts 集合：

• 现在可以包含静态资源（如图片、PDF等）和Markdown文件
• 但如果集合没有设置 output: true 元数据，则：
  • 文档不会被输出
  • 静态资源也不会被输出

4. 排除规则增强

默认排除列表已扩展，现在包含更多常见目录：

exclude:
- .sass-cache/
- .jekyll-cache/
- gemfiles/
- Gemfile
- Gemfile.lock
- node_modules/
- vendor/bundle/
- vendor/cache/
- vendor/gems/
- vendor/ruby/

重要变化：

• 用户配置文件中的 exclude 数组不再覆盖默认排除列表
• 用户配置的排除项会追加到默认列表中
• 要强制包含被排除的文件，需使用 include 数组

5. Kramdown 2.0 升级

Jekyll 4.0 完全移除了对 kramdown 1.x 的支持：

• 核心功能之外的特性需要额外安装扩展
• kramdown-parser-gfm 会自动安装
• 其他扩展需要手动添加到 Gemfile

PDF转换说明： Jekyll 核心不再直接支持Markdown转PDF，需要自定义转换器插件：

module Jekyll
  class Markdown2PDF < Converter
    safe true
    priority :low

    def matches(ext)
      ext =~ /^\.markdown$/
    end

    def convert(content)
      Kramdown::Document.new(content).to_pdf
    end

    def output_ext
      ".pdf"
    end
  end
end

插件开发者注意事项

如果你的插件涉及以下操作：

site.liquid_renderer.file(path).parse(content)

请注意：

1. 对于相同路径，返回的模板对象始终相同
2. 确保传递给模板的 payload 没有被缓存
3. 如果需要每次都获得新模板，应直接使用 Liquid::Template.parse

已移除的配置选项

Jekyll 4.0 移除了所有在之前版本中已标记为废弃的配置选项。这些选项将：

• 不再输出弃用警告
• 不再自动映射到新选项
• 可能导致配置错误（如果值类型不正确）

升级建议

1. 先在开发环境测试升级
2. 逐步检查并修改模板中的 post_url 标签
3. 验证自定义插件是否兼容新渲染机制
4. 检查排除规则是否符合预期
5. 更新依赖的 kramdown 扩展

通过遵循这些指南，你可以顺利将项目从 Jekyll 3.x 迁移到 4.x 版本，享受更快的构建速度和更现代化的功能集。

jekyll 项目地址: https://gitcode.com/gh_mirrors/jek/jekyll