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

古いバージョンの Jekyll からアップグレードしますか？Jekyll 3 ではいくつか変更点がありますので、知っておく必要があります。

始める前に、最新バージョンの Jekyll を取得してください。

gem update jekyll

バージョン 3.2 以降、Jekyll には Ruby バージョン >= 2.1 が必要です。

詳細

新しい Jekyll サイトをすぐに立ち上げたいですか？jekyll new SITENAME を実行するだけで、Jekyll サイトの最小限の構成を持つ新しいフォルダが作成されます。

site.collections の変更

2.x では、site.collections の反復処理では、コレクションラベルとコレクションオブジェクトがそれぞれ最初と2番目の項目として含まれる配列が生成されていました。3.x では、この複雑さが解消され、反復処理では単にコレクションオブジェクトが生成されるようになりました。テンプレートで簡単な変換を行う必要があります。

collection[0] は collection.label になります
collection[1] は collection になります

site.collections を反復処理するときは、上記の変換が行われるようにしてください。

Jekyll 2 の site.collections.myCollection の場合は、次のようになります。

{% assign myCollection = site.collections | where: "label", "myCollection" | first %}

最初は少し面倒ですが、大きな for ループよりも簡単です。

Textile のサポート

Textile のネイティブサポートを削除しました。今後は、Textile ファイルを扱うには jekyll-textile-converter プラグインをインストールする必要があります。

削除された依存関係

コアチームがオプションであると感じた多くの依存関係を削除しました。したがって、3.0 では、これらの機能を使用する場合は、明示的にインストールして含める必要があります。それらは以下のとおりです。

jekyll-paginate – 過去の Jekyll のページネーションソリューション
jekyll-coffeescript – CoffeeScript の処理
jekyll-gist – gist Liquid タグ
pygments.rb – Pygments ハイライター
redcarpet – Markdown プロセッサ
toml – 設定ファイル用の YAML の代替
classifier-reborn – site.related_posts 用

未来の投稿

2.x で見られた機能の後退のように、--future フラグは自動的に有効になっていました。future フラグを使用すると、投稿者は投稿に未来の日付を与え、システム時間が投稿時間以降になるまでビルドから除外することができます。Jekyll 3 では、これが修正されました。現在、--future はデフォルトで無効になっています。つまり、jekyll build または jekyll serve を実行するときに、未来の日付の投稿を生成したい場合は、--future を含める必要があります。

GitHub Pages での未来の投稿

上記のルールの例外は、GitHub Pages サイトです。これらのサイトでは、過去の整合性を維持するために、--future フラグはデフォルトで有効のままです。

レイアウトメタデータ

導入: layout。Jekyll 2 以前では、レイアウトのメタデータはすべて Liquid の page 変数にマージされていました。これにより、データのマージ方法に多くの混乱が生じ、予期しない動作が発生していました。Jekyll 3 では、すべてのレイアウトデータは Liquid の layout を介してアクセスできるようになりました。たとえば、レイアウトのフロントマターに class: my-layout がある場合、レイアウトは {{ layout.class }} を介してそれにアクセスできます。

シンタックスハイライターの変更

初めて、デフォルトのシンタックスハイライターが highlight タグとバッククォートコードブロックで変更されました。Pygments.rb の代わりに、現在は Rouge になっています。特定のオプション（hl_lines など）を指定して highlight タグを使用していた場合、Rouge を使用すると利用できない場合があります。Pygments の使用に戻すには、_config.yml ファイルで highlighter: pygments を設定し、gem install pygments.rb を実行するか、プロジェクトの Gemfile に gem "pygments.rb" を追加します。

相対パーマリンクのサポートの削除

Jekyll 3 以降では、相対パーマリンクは非推奨になりました。Jekyll 2 以前を使用してサイトを作成した場合、serve または build を試みると、次のエラーが発生する可能性があります。

Since v3.0, permalinks for pages in subfolders must be relative to the site
source directory, not the parent directory. Check
https://jekyll.dokyumento.jp/docs/upgrading/ for more info.

これは、_config.yml ファイルから次の行を削除することで修正できます。

relative_permalinks: true

パーマリンクが末尾のスラッシュを自動的に追加しなくなった

Jekyll 2 では、permalink: フィールドから構築された URL には、末尾にスラッシュ（/）が自動的に追加されていました。Jekyll 3 では、permalink: URL に末尾のスラッシュが自動的に追加されなくなりました。これにより、ページへの古いリンクが 404 エラーを返す可能性があります。たとえば、以前のページに YAML permalink: /:year-:month-:day-:title が含まれていて、URL example.com/2016-02-01-test/（末尾のスラッシュに注意）になったとします。Jekyll は内部的に 2016-02-01-test という名前のフォルダを生成します。Jekyll 3 では、同じ permalink: でファイル 2016-02-01-test.html が生成され、同じページの URL は example.com/2016-02-01-test になり、結果として古い URL へのリンクはすべて 404 エラーになります。同じ URL を維持してこの問題を回避するには、permalink: フィールドに末尾のスラッシュを追加する必要があります。たとえば、permalink: /:year-:month-:day-:title/ のようにします。

投稿がすべて消えた！どこに行ったの！

_config.yml ファイルに future: true を追加してみてください。今表示されていますか？表示されている場合は、Ruby が時間を解析する方法に関する問題に陥っています。各投稿が予期しないタイムゾーンで読み取られており、コンピュータの現在時刻と比較すると、「未来」にあることになります。これを修正するには、各投稿にタイムゾーンオフセットを追加します（そして、_config.yml ファイルから future: true を削除してください）。たとえば、カリフォルニアから記述している場合は、これを

---
date: 2016-02-06 19:32:10
---

これに変更します（オフセットに注意）。

---
date: 2016-02-06 19:32:10 -0800
---

カテゴリが機能しなくなった！

カテゴリを /_posts/code/2008-12-24-closures.md として構成した場合、カテゴリを _posts ディレクトリの上に配置するようにディレクトリを再構成する必要があります。次に例を示します: /code/_posts/2008-12-24-closures.md。

何か見落としていませんか？上の「このページを改善する」をクリックしてセクションを追加してください。ありがとうございます！