Jekyll 从 3.x 升级到 4.x 注意事项

Jekyll 4 中有一些变化需要你特别注意。

在开始之前，你需要确保已经安装 Ruby 2.5.0 或更高版本。

请在终端运行以下命令进行检查：

ruby -v
ruby 3.1.3p185 (2022-11-24 revision 1a6b16756e)

如果你当前使用的 Ruby 版本 >= 2.5.0，那么继续获取最新版本的 Jekyll：

gem update jekyll

`post_url` 标签与 Baseurl

post_url 标签现在已经内置了 relative_url 过滤器，因此会自动为文章的 url 添加网站的 baseurl。

请确保将所有 post_url 的用法修改如下：

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

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

模板渲染

为了提升整体构建速度，我们对 Jekyll 解析与渲染模板的方式进行了调整。

现在，Jekyll 会先解析一次模板，并将其缓存在内部，然后根据页面和文档需要重复使用已解析的模板进行渲染。

这样做的缺点是，一些社区编写的插件可能无法像以前那样正常工作。

未渲染集合中的静态文件

除了 posts 之外的 Collection，现在可以同时包含静态资源文件与 Markdown 文件。

但是，如果该 Collection 没有配置 output: true 元数据，那么其中的 文档（documents） 与 静态资源（static assets） 都不会输出到目标目录。

致插件作者

如果你的插件依赖如下代码：

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

请注意，这行代码返回的 template（即 Liquid::Template 实例）对于相同的 path 始终是 同一个对象。

然后，这个 template 会像以前一样根据传入的 payload 进行渲染。

因此，你需要确保插件中的 payload 没有被缓存或记忆化（memoized）。

如果你必须保证每次获取的 template 都是 不同对象，那么请直接调用 Liquid::Template：

- template = site.liquid_renderer.file(path).parse(content)
+ template = Liquid::Template.parse(content)

排除规则变更

我们增强了默认的排除（exclude）列表。

现在默认配置如下：

# 默认排除项
exclude:
- .sass-cache/
- .jekyll-cache/
- gemfiles/
- Gemfile
- Gemfile.lock
- node_modules/
- vendor/bundle/
- vendor/cache/
- vendor/gems/
- vendor/ruby/

新的变化是：

用户配置文件中的 exclude 数组 不会再覆盖默认排除列表。

现在，用户定义的排除项只会被追加到默认列表中（如果该项尚未存在）。

如果你想强制处理已被排除的目录或文件，可以将它们添加到 include 数组中：

# 覆盖你的 excluded 配置以及默认 include 数组（[".htaccess"]）
include:
  - .htaccess
  - node_modules/uglifier/index.js

上述配置表示：

Jekyll 仅处理 node_modules/uglifier/index.js，而 node_modules 目录中的其他文件仍会被忽略，因为该目录默认属于排除项。

请注意：

默认的 include 数组依然会被你配置文件中的 include 数组覆盖。

因此，如果你需要生成 .htaccess 文件，请务必手动将其添加到 include 列表中。

Kramdown v2

Jekyll 已完全移除对 kramdown-1.x 的支持。

从 v2.0 开始，kramdown 需要额外安装特定扩展，才能使用某些核心功能之外的特性。

在上述链接列出的所有扩展中，kramdown-parser-gfm 会随着 Jekyll 4.0 自动安装。

其余扩展则需要用户根据实际需求，在 Gemfile 中手动添加对应 gem。

注意事项：

kramdown-converter-pdf 会被 Jekyll Core 忽略。

如果你希望让 Jekyll 将 Markdown 转换为 PDF，需要依赖一个继承自 Jekyll::Converter 的插件，并实现所需方法。

例如：

module Jekyll
  External.require_with_graceful_fail "kramdown-converter-pdf"

  class Markdown2PDF < Converter
    safe true
    priority :low

    def matches(ext)
      # 仅匹配扩展名严格为 ".markdown" 的文件
      ext =~ /^\.markdown$/
    end

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

    def output_ext
      ".pdf"
    end
  end
end

提供带版本号 Jekyll 环境镜像的服务商（例如 Docker 镜像、GitHub Pages 等）

需要在 Jekyll 4.0 环境中手动将 kramdown 扩展 gem 加入白名单。

弃用的配置选项

Jekyll 4.0 已移除对所有旧版配置项的支持。

这些配置项在之前多个版本中已经被标记为弃用（deprecated）。

因此：

我们不再在检测到旧配置键时输出弃用警告，也不会再自动将旧配置值兼容映射到新的配置项。

根据不同情况：

某些旧配置会被直接忽略
某些仍然有效但值类型错误的配置，会抛出 InvalidConfigurationError 错误