このページを改善する

テーマ

Jekyllには、コミュニティで管理されているテンプレートとスタイルを活用してサイトの表示をカスタマイズできる、拡張性の高いテーマシステムがあります。Jekyllのテーマはプラグインを指定し、アセット、レイアウト、インクルード、スタイルシートを、サイトのコンテンツで上書きできる方法でパッケージ化します。

テーマを選ぶ

さまざまなギャラリーでテーマを探してプレビューできます

• GitHub.com #jekyll-theme リポジトリ
• jamstackthemes.dev
• jekyllthemes.org
• jekyllthemes.io
• jekyll-themes.com

参照：リソース。

gemベースのテーマについて

新しいJekyllサイトを作成する（jekyll new <PATH>コマンドを実行する）と、JekyllはMinimaというgemベースのテーマを使用するサイトをインストールします。

gemベースのテーマでは、サイトの一部のディレクトリ（assets、_data、_layouts、_includes、_sassディレクトリなど）はテーマのgemに格納され、直接表示されません。ただし、必要なすべてのディレクトリは、Jekyllのビルドプロセス中に読み取られ、処理されます。

Minimaの場合、Jekyllサイトディレクトリには次のファイルのみが表示されます

.
├── Gemfile
├── Gemfile.lock
├── _config.yml
├── _posts
│   └── 2016-12-04-welcome-to-jekyll.markdown
├── about.markdown
└── index.markdown

GemfileとGemfile.lockファイルは、Bundlerによって使用され、Jekyllサイトの構築に必要なgemとgemのバージョンを追跡します。

gemベースのテーマを使用すると、テーマ開発者は、テーマgemを持っているすべての人が利用できる更新プログラムを簡単に作成できます。更新がある場合、テーマ開発者は更新をRubyGemsにプッシュします。

テーマgemをお持ちの場合は、必要に応じてbundle updateを実行して、プロジェクト内のすべてのgemを更新できます。または、<THEME>をminimaなどのテーマ名に置き換えて、bundle update <THEME>を実行して、テーマgemのみを更新することもできます。テーマ開発者が行った新しいファイルや更新（スタイルシートやインクルードなど）は、プロジェクトに自動的に取り込まれます。

gemベースのテーマの目標は、堅牢で継続的に更新されるテーマのすべての利点を、すべてのテーマファイルが邪魔になったり、主な焦点であるコンテンツの作成を過度に複雑にすることなく、すべての人に享受できるようにすることです。

テーマのデフォルトを上書きする

Jekyllのテーマは、デフォルトのデータ、レイアウト、インクルード、スタイルシートを設定します。ただし、テーマのデフォルトは、独自のサイトコンテンツで上書きできます。

テーマのレイアウトまたはインクルードを置き換えるには、変更する特定のファイルの_layoutsまたは_includesディレクトリにコピーを作成するか、上書きするファイルと同じ名前を付けてファイルを作成します。

たとえば、選択したテーマにpageレイアウトがある場合、_layoutsディレクトリ（つまり、_layouts/page.html）に独自のpageレイアウトを作成することで、テーマのレイアウトを上書きできます。

コンピューターでテーマのファイルを見つけるには

1. bundle info --pathの後にテーマのgemの名前を入力して実行します。たとえば、Jekyllのデフォルトテーマの場合はbundle info --path minimaです。

   これにより、gemベースのテーマファイルの場所が返されます。たとえば、Minimaテーマのファイルは、macOSでは/usr/local/lib/ruby/gems/2.6.0/gems/minima-2.5.1にある場合があります。

2. Finderまたはエクスプローラーでテーマのディレクトリを開く

   # On MacOS
   open $(bundle info --path minima)
   
   # On Windows
   # First get the gem's installation path:
   #
   #   bundle info --path minima
   #   => C:/Ruby26-x64/lib/ruby/gems/3.1.3/gems/minima-2.5.1
   #
   # then invoke explorer with above path, substituting `/` with `\`
   explorer C:\Ruby26-x64\lib\ruby\gems\3.1.3\gems\minima-2.5.1
   
   # On Linux
   xdg-open $(bundle info --path minima)
   

   Finderまたはエクスプローラーウィンドウが開き、テーマのファイルとディレクトリが表示されます。Minimaテーマgemには、これらのファイルが含まれています

   .
   ├── LICENSE.txt
   ├── README.md
   ├── _includes
   │   ├── disqus_comments.html
   │   ├── footer.html
   │   ├── google-analytics.html
   │   ├── head.html
   │   ├── header.html
   │   ├── icon-github.html
   │   ├── icon-github.svg
   │   ├── icon-twitter.html
   │   └── icon-twitter.svg
   ├── _layouts
   │   ├── default.html
   │   ├── home.html
   │   ├── page.html
   │   └── post.html
   ├── _sass
   │   ├── minima
   │   │   ├── _base.scss
   │   │   ├── _layout.scss
   │   │   └── _syntax-highlighting.scss
   │   └── minima.scss
   └── assets
       └── main.scss
   

テーマのファイルが明確に理解できたら、Jekyllサイトディレクトリに同じ名前のファイルを作成することで、テーマファイルを上書きできます。

たとえば、2番目の例として、Minimaのフッターを上書きしたいとします。Jekyllサイトで、_includesフォルダーを作成し、footer.htmlという名前のファイルをそのフォルダーに追加します。Jekyllは、Minimaテーマgemのfooter.htmlファイルの代わりに、サイトのfooter.htmlファイルを使用するようになります。

スタイルシートを変更するには、メインsassファイル（Minimaテーマでは_sass/minima.scss）をサイトのソースの_sassディレクトリにもコピーするという追加の手順を実行する必要があります。

Jekyllは、次のフォルダーで要求されたファイルについて、テーマのデフォルトを探す前に、まずサイトのコンテンツを探します

• /assets
• /_data
• /_layouts
• /_includes
• /_sass

テーマファイルのコピーを作成すると、それらのファイルのテーマの更新を受信できなくなることに注意してください。すべてのスタイルシートでテーマの更新を引き続き取得するための代替方法は、独自の追加の、元の名前のCSSファイルで、より特異性の高いCSSセレクターを使用することです。

上書きできるファイルの詳細については、選択したテーマのドキュメントとソースリポジトリを参照してください。

_dataディレクトリのあるテーマ4.3.0

バージョン4.3.0以降、Jekyllはテーマの_dataディレクトリも考慮します。これにより、データをテーマ全体に配布できます。

典型的な例は、デザイン要素内で使用されるテキストです。

テーマがインクルードファイルtestimonials.htmlを提供しているとします。このデザイン要素は、ページに新しいセクションを作成し、お客様の声のリストの上にh3見出しを配置します。

テーマ開発者は、おそらく見出しを英語で作成し、HTMLソースコードに直接配置します。

テーマの利用者は、インクルードファイルをプロジェクトにコピーして、見出しを置き換えることができます。

_dataディレクトリを考慮することで、この標準タスクの別の解決策があります。

デザイナーは、テキストをデザインテンプレートに直接入力する代わりに、テキストカタログ（例：site.data.i18n.testimonials.header）への参照を追加し、テーマのデータディレクトリに_data/i18n/testimonials.ymlファイルを作成します。

このファイルでは、見出しはheaderキーの下に配置され、残りはJekyllが処理します。

テーマ開発者にとって、これは一見すると以前よりも大きな労力です。

ただし、テーマの利用者にとっては、カスタマイズが大幅に簡素化されます。

ドイツの顧客がテーマを使用しているとします。彼女がお客様の声のデザイン要素の翻訳された見出しを取得するには、site.data.i18n.testimonials.headerキーを使用してプロジェクトディレクトリにデータファイルを作成し、ドイツ語の翻訳または選択した見出しをその上に配置するだけで、デザイン要素はすでにカスタマイズされています。

彼女はもはやインクルードファイルをプロジェクトディレクトリにコピーしてカスタマイズする必要がなく、最も重要なことは、テーマ開発者がテキストファイルを使用してテキストモジュールを中央で変更する可能性を提供してくれたため、テーマのすべての更新を放棄する必要がなくなりました。

データファイルは高度な柔軟性を提供します。テーマ開発者がテキストモジュールを配置する場所は、テーマの利用者の場所とは異なる場合があり、予期せぬ問題が発生する可能性があります。

上記の例に関連して、テーマの_data/i18n/testimonials.ymlファイルからの上書きキーsite.data.i18n.testimonials.headerは、コンシューマーサイトの3つの異なる場所に配置できます。

• _data/i18n.yml（キー：testimonials.header）
• _data/i18n/testimonials.yml（キー：header）（上記の例のレイアウトを反映）
• _data/i18n/testimonials/header.yml（キーなし、見出しはファイルに直接入力できます）

テーマ開発者は、テーマが提供するデザイン要素のテキストモジュールの設定に迷っている利用者をサポートする場合、このあいまいさを念頭に置いておく必要があります。

データ機能を使用する場合、導入するキーは、存在する場合にテーマの動作を変更するものなのか、それとも単に表示されるデータなのかを自問自答してください。テーマの動作を変更する場合は、site.configに配置する必要があります。そうでない場合は、site.dataで提供しても問題ありません。

テーマの動作を変更するデータをバンドルすることは、**アンチパターン**と見なされ、使用は強くお勧めしません。提供されるすべてのデータが、必要に応じてテーマの利用者によって簡単に上書きできることを保証することは、テーマの作成者次第です。

gemベースのテーマを通常のテーマに変換する

gemベースのテーマを取り除き、すべてのファイルがJekyllサイトディレクトリに存在し、テーマgemには何も格納されていない通常のテーマに変換したいとします。

これを行うには、テーマgemのディレクトリからファイルをJekyllサイトディレクトリにコピーします。（たとえば、Jekyllサイトを/myblogに作成した場合は、/myblogにコピーします。詳細は前のセクションを参照してください。）

次に、テーマによって参照されていたプラグインについてJekyllに指示する必要があります。これらのプラグインは、テーマのgemspecファイルでランタイム依存関係として見つけることができます。たとえば、Minimaテーマを変換する場合、次のように表示される場合があります

spec.add_runtime_dependency "jekyll-feed", "~> 0.12"
spec.add_runtime_dependency "jekyll-seo-tag", "~> 2.6"

これらの参照は、次の2つの方法のいずれかでGemfileに含める必要があります。

それぞれをGemfileと_config.ymlの両方に個別にリストすることもできます。

# ./Gemfile

gem "jekyll-feed", "~> 0.12"
gem "jekyll-seo-tag", "~> 2.6"

# ./_config.yml

plugins:
  - jekyll-feed
  - jekyll-seo-tag

または、以下のように、GemfileにJekyllプラグインとして明示的にリストし、_config.ymlを更新しないこともできます。

# ./Gemfile

group :jekyll_plugins do
  gem "jekyll-feed", "~> 0.12"
  gem "jekyll-seo-tag", "~> 2.6"
end

いずれの場合も、bundle updateを実行することを忘れないでください。

GitHub Pagesで公開する場合は、GitHub PagesはBundler経由でプラグインを読み込まないため、_config.ymlのみを更新する必要があります。

最後に、Gemfileと設定ファイルからテーマgemへの参照を削除します。たとえば、minimaを削除するには、

• Gemfileを開き、gem "minima", "~> 2.5"を削除します。
• _config.ymlを開き、theme: minimaを削除します。

これで、bundle updateを実行しても、テーマgemの更新は取得されなくなります。

gemベースのテーマのインストール

jekyll new <PATH>コマンドは、gemベースのテーマを使用して新しいJekyllサイトを作成する唯一の方法ではありません。オンラインでgemベースのテーマを見つけて、Jekyllプロジェクトに組み込むこともできます。

たとえば、RubyGemsでjekyll themeを検索して、他のgemベースのテーマを見つけることができます。（すべてのテーマがテーマ名にjekyll-themeという規則を使用しているわけではないことに注意してください。）

gemベースのテーマをインストールするには

1. サイトのGemfileにテーマgemを追加します。

   # ./Gemfile
   
   # This is an example, declare the theme gem you want to use here
   gem "jekyll-theme-minimal"
   

   または、jekyll newコマンドで開始した場合は、gem "minima", "~> 2.0"を目的のgemに置き換えます。例：

   # ./Gemfile
   
   - gem "minima", "~> 2.5"
   + gem "jekyll-theme-minimal"
   

2. テーマをインストールします。

   bundle install
   

3. テーマを有効にするには、サイトの_config.ymlに以下を追加します。

   theme: jekyll-theme-minimal
   

4. サイトをビルドします。

   bundle exec jekyll serve
   

サイトのGemfileには複数のテーマをリストできますが、サイトの_config.ymlで選択できるテーマは1つだけです。

GitHub PagesでJekyllサイトを公開する場合は、GitHub Pagesは一部のgemベースのテーマのみをサポートしていることに注意してください。GitHub Pagesは、GitHubでホストされているテーマをremote_theme設定を使用してgemベースのテーマのように使用することもサポートしています。

gemベースのテーマの作成

Jekyllテーマの開発者（テーマの利用者ではなく）である場合は、テーマをRubyGemsにパッケージ化し、ユーザーがBundlerを介してインストールできるようにすることができます。

Ruby gemの作成に慣れていない場合でも、心配しないでください。Jekyllは、new-themeコマンドを使用して新しいテーマのscaffoldingを支援します。テーマ名を引数としてjekyll new-themeを実行します。

例を次に示します。

jekyll new-theme jekyll-theme-awesome
    create /path/to/jekyll-theme-awesome/_layouts
    create /path/to/jekyll-theme-awesome/_includes
    create /path/to/jekyll-theme-awesome/_sass
    create /path/to/jekyll-theme-awesome/_layouts/page.html
    create /path/to/jekyll-theme-awesome/_layouts/post.html
    create /path/to/jekyll-theme-awesome/_layouts/default.html
    create /path/to/jekyll-theme-awesome/Gemfile
    create /path/to/jekyll-theme-awesome/jekyll-theme-awesome.gemspec
    create /path/to/jekyll-theme-awesome/README.md
    create /path/to/jekyll-theme-awesome/LICENSE.txt
    initialize /path/to/jekyll-theme-awesome/.git
    create /path/to/jekyll-theme-awesome/.gitignore
Your new Jekyll theme, jekyll-theme-awesome, is ready for you in /path/to/jekyll-theme-awesome!
For help getting started, read /path/to/jekyll-theme-awesome/README.md.

対応するフォルダにテンプレートファイルを追加します。次に、必要に応じて.gemspecファイルとREADMEファイルを完成させます。

レイアウトとインクルード

テーマのレイアウトとインクルードは、Jekyllサイトと同じように機能します。レイアウトはテーマの/_layoutsフォルダに配置し、インクルードはテーマの/_includesフォルダに配置します。

たとえば、テーマに/_layouts/page.htmlファイルがあり、ページのfrontmatterにlayout: pageが指定されている場合、Jekyllは最初にサイトの_layoutsフォルダでpageレイアウトを探し、存在しない場合はテーマのpageレイアウトを使用します。

アセット

/assets内のファイルは、ユーザーが同じ相対パスを持つファイルを持っていない限り、ビルド時にユーザーのサイトにコピーされます。SCSS、画像、webfontなど、あらゆる種類のアセットをここに配置できます。これらのファイルは、Jekyllのページや静的ファイルのように動作します。

• ファイルの先頭にfrontmatterがある場合、レンダリングされます。
• ファイルにfrontmatterがない場合、結果のサイトにコピーされるだけです。

これにより、テーマの作成者は、レイアウトが/assets/styles.cssとして依存できるデフォルトの/assets/styles.scssファイルを提供できます。

/assets内のすべてのファイルは、Jekyllをサイトで使用する場合と同様に、コンパイルされたサイトの/assetsフォルダに出力されます。

スタイルシート

テーマのスタイルシートは、Jekyllサイトを作成する場合と同様に、テーマの_sassフォルダに配置する必要があります。

_sass
└── jekyll-theme-awesome.scss

テーマのスタイルは、@importディレクティブを使用してユーザーのスタイルシートに含めることができます。

@import "{{ site.theme }}";

テーマgemの依存関係3.5.0

Jekyllは、サイトの設定ファイルのplugins配列に明示的に含まれていなくても、テーマgemのホワイトリストに登録されたすべてのruntime_dependenciesを自動的に要求します。（注：ホワイトリストへの登録は、--safeオプションを使用してビルドまたはサーブする場合にのみ必要です。）

これにより、エンドユーザーは、テーマgemが意図したとおりに動作するために設定ファイルに含める必要があるプラグインを追跡する必要がなくなります。

テーマgemの事前設定4.0

Jekyllは、テーマgemのルートにある_config.ymlを読み込み、そのデータをサイトの既存の設定データにマージします。

ただし、テーマ内からロードされる他のエンティティとは異なり、設定ファイルのロードには、以下にまとめるように、いくつかの制限があります。

• Jekyllのデフォルト設定は、テーマ設定でオーバーライドできません。それは*依然としてユーザーの責任です。*
• テーマ設定ファイルは、safe modeとシンボリックリンクが指すファイルがテーマgem内の正当なファイルであるかどうかに関係なく、シンボリックリンクにすることはできません。
• テーマ設定は、キーと値のペアのセットである必要があります。空の設定ファイル、キーの下に*単にアイテムをリストする*設定ファイル、または単純なテキスト文字列のみを含む設定ファイルは、単にサイレントに無視されます。ユーザーはこの不一致に関する警告やログ出力を受け取りません。
• テーマ設定で定義された設定は、ユーザーがオーバーライドできます。

この機能はテーマの導入を容易にするためのものであり、制限により、テーマ設定が懸念される方法でビルドに影響を与えることがないようにしています。テーマに必要なプラグインは、ユーザーが手動でリストするか、テーマのgemspecファイルで提供する必要があります。

この機能により、テーマgemは*テーマ固有の設定変数*をすぐに使用できます。

テーマのドキュメント化

テーマには、サイトの作成者がテーマをインストールして使用する方法を説明する/README.mdファイルを含める必要があります。 どのようなレイアウトが含まれていますか？ どのようなインクルードがありますか？ サイトの設定ファイルに特別なものを追加する必要がありますか？

スクリーンショットの追加

テーマは視覚的です。 プログラムで取得できるように、テーマのリポジトリ内に/screenshot.pngとしてスクリーンショットを含めることで、ユーザーにテーマの外観を示します。 このスクリーンショットは、テーマのドキュメントにも含めることができます。

テーマのプレビュー

テーマを作成中にプレビューするには、たとえば、/index.htmlファイルと/page.htmlファイルにダミーコンテンツを追加すると役立つ場合があります。 これにより、Jekyllサイトをプレビューする場合と同様に、jekyll buildコマンドとjekyll serveコマンドを使用してテーマをプレビューできます。

テーマをローカルでプレビューする場合は、コンパイルされたサイトもテーマを配布するときに含まれないように、テーマの.gitignoreファイルに/_siteを追加してください。

テーマの公開

テーマはRubyGems.orgを介して公開されます。 無料で作成できるRubyGemsアカウントが必要です。

1. まず、gitリポジトリに配置する必要があります。

   git init # Only the first time
   git add -A
   git commit -m "Init commit"
   

2. 次に、次のコマンドを実行してテーマをパッケージ化します。jekyll-theme-awesomeをテーマの名前に置き換えます。

   gem build jekyll-theme-awesome.gemspec
   

3. 最後に、次のコマンドを実行して、パッケージ化されたテーマをRubyGemsサービスにプッシュします。ここでも、jekyll-theme-awesomeをテーマの名前に置き換えます。

   gem push jekyll-theme-awesome-*.gem
   

4. テーマの新しいバージョンをリリースするには、gemspecファイル（この例ではjekyll-theme-awesome.gemspec）のバージョン番号を更新してから、上記のステップ1〜3を繰り返します。テーマのバージョンを更新する際は、セマンティックバージョニングに従うことをお勧めします。