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)、その行からの戻り値（template、Liquid::Templateのインスタンス）は、特定のpathに対して常に同じオブジェクトになります。
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配列によって上書きされなくなったことです。ユーザーの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エラーが発生します。