从 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 过滤器合并到自身中，因此会自动将你网站的 baseurl 前置到帖子的 url 值。

请确保你更改 post_url 用法的所有实例，如下所示

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

模板渲染

我们略微改变了 Jekyll 解析和渲染各种模板的方式，以改善整体构建时间。Jekyll 现在解析模板一次，将其缓存到内部，然后根据页面和文档的需要多次渲染解析后的模板。

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

未渲染集合中的静态文件

除了 posts 之外的集合可以包含静态资产和 Markdown 文件。但是，如果集合尚未使用元数据 output: true 进行配置，那么其文档和静态资产都不会输出到目标目录。

对于插件作者

如果您的插件依赖于以下代码：site.liquid_renderer.file(path).parse(content)，请注意，对于给定的 path，该行中的返回值（template，Liquid::Template 的一个实例）将始终是相同对象。
template 实例随后会根据传递给它的 payload 进行渲染，与之前相同。因此，您必须确保payload 在您的插件实例中没有被记忆化或缓存。

如果要求您从上述步骤中获取的 template 始终不同，您可以直接调用Liquid::Template

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

排除更改

我们增强了默认排除数组。它现在看起来如下所示

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

新内容是，此数组不再被用户配置文件中的 exclude 数组覆盖。用户的排除项只是添加到上述默认数组中（如果该项尚未被排除）。

要强制“处理”已被排除的目录或文件，请将它们列在 include 数组中

# overrides your excluded items configuration and the default include array ([".htaccess"])
include:
  - .htaccess
  - node_modules/uglifier/index.js

上述配置指示 Jekyll 仅处理 node_modules/uglifier/index.js，同时忽略 node_modules 目录中的所有其他文件，因为该目录默认情况下被“排除”。

请注意，默认 include 数组仍然会被配置文件中的 include 数组覆盖。因此，如果您需要该文件出现在生成的网站中，请务必将 .htaccess 添加到列表中。

Kramdown v2

Jekyll 已完全放弃对 kramdown-1.x 的支持。

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

在上述报告中列出的所有扩展中，gem 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)
      # match only files that have an extension exactly ".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 已放弃对所有旧版配置选项的支持，这些选项在之前的系列中已弃用多个版本。

为此，当我们遇到旧版配置键时，不再输出弃用警告，也不会将它们的值优雅地分配给较新的对应项。根据键的不同，它将被忽略或引发 InvalidConfigurationError 错误，如果键仍然有效，但关联的值不是有效类型。