從 3.x 升級到 4.x

Jekyll 4 中有些地方有所變更。

在我們深入探討之前，您需要安裝至少 Ruby 2.5.0。

在您的終端機中執行以下指令進行檢查

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

如果您使用的是 >= 2.5.0 的受支援 Ruby 版本，請繼續取得 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 現在會分析範本一次，將其快取在內部，然後依據您的網頁和文件需要多次呈現已分析的範本。

這樣做的缺點是，某些社群撰寫的外掛程式可能無法像以前一樣運作。

未呈現的彙編中的靜態檔案

除了 文章 之外的彙編可以包含靜態資產和 Markdown 檔案。但是，如果彙編尚未設定為具有元資料 輸出：真實，則其文件和靜態資產都不會輸出到目標目錄。

針對外掛程式作者

如果您的外掛程式仰賴下列程式碼： site.liquid_renderer.file(路徑).parse(內容)，請注意，該行的傳回值（範本，Liquid::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/

新的部分是，這個陣列不再會被使用者設定檔中的 排除 陣列覆寫。使用者的排除項目會簡單地新增到上述預設陣列（如果該項目尚未排除）。

若要強制「處理」已排除的目錄或檔案，請將它們列在 包含 陣列中

# 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 等）的供應商必須在他們的發行版中手動將 kramdown 的擴充套件寶石加入白名單，以適用於 Jekyll 4.0。

已棄用的組態選項

Jekyll 4.0 已終止支援所有舊版組態選項，這些選項已在先前系列的多次發行中被棄用。

因此，當我們遇到舊版組態金鑰時，我們將不再輸出棄用警告，也不會優雅地將其值指定給較新的對應項目。根據金鑰的不同，它將被忽略或引發 InvalidConfigurationError 錯誤，如果金鑰仍然有效，但關聯值不是有效類型。