Improve this page

3.xから4.xへのアップグレード

Jekyll 4にはいくつかの変更点があります。

アップグレード前に、最新のRuby 2.5.0のインストールが必要です。

ターミナルで次を実行して確認してください。

ruby -v
ruby 2.7.1p83 (2020-03-31 revision a0c7c23c9c)

サポートされている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以外のコレクションには、マークダウンファイルと共に静的ファイルを含めることができます。しかし、コレクションにoutput: trueの設定がされていなければ、ドキュメントも静的ファイルも出力されません。

プラグイン作成者へ

• プラグインがsite.liquid_renderer.file(path).parse(content)のコードに依存している場合、その行からの戻り値（template、Liquid::Templateのインスタンス）は、与えられたpathと常に同じオブジェクトになることに注意してください。
  templateインスタンスは、渡されたpayloadに関して、以前のようにレンダリングされます。したがって、payloadがプラグインインスタンスに記憶またはキャッシュされないようにする必要があります。
• 上記のステップから得られるtemplateが毎回異なるという要件がある場合は、Liquid::Templateを直接呼び出すことができます。 ```diff
  • 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のサポートを完全に終了しました。

kramdown v2.0 以降では、kramdownのコア機能以外に特定の機能を使用するには、対応する拡張機能を追加インストールする必要があります。

上記リンクのレポートの拡張機能の一覧うち、gem kramdown-parser-gfmはJekyll 4.0とともに自動的にインストールされます。残りの拡張機能は、Gemfileで拡張機能のgem-nameをリストアップすることによって、目的の機能に応じてユーザーが手動でインストールする必要があります。

メモ:

• 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 Image、GitHub Pagesなど）を提供するベンダーは、Jekyll 4.0のディストリビューションでkramdownの拡張機能のgemを手動でホワイトリストに登録する必要があります。

非推奨の設定オプション

Jekyll 4.0では、以前のシリーズの複数のリリースで廃止された、すべてのレガシー設定オプションのサポートを終了しました。

そのため、レガシー構成キーに遭遇したときに非推奨の警告を出力することも、それらを適切に新しい対応した値に割り当てることもしません。キーはまだ有効であるが、関連付けられた値が有効なタイプでない場合、キーに応じて、無視されるか、 InvalidConfigurationErrorエラーが発生します。