Improve this page

テーマ

Jekyllには幅広いテーマシステムがあり、サイトの表現をカスタマイズできる、コミュティーで管理されたテンプレートとスタイルを提供します。Jekyllのテーマは、プラグインとパッケージ化されたAsset、レイアウト、インクルード、スタイルシートで、サイトのコンテンツで上書きできます。

テーマをピックアップ

さまざまなギャラリーでテーマをプレビューし、見つけることができます。

gemベーステーマを理解する

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

gemベーステーマでは、いくつかのサイトディレクトリ（assetsや_layouts、_includes、_sassディレクトリ）はテーマに内包されていて、直接見えるところからは隠れています。ですが、全ての必要なディレクトリはJekyllが構築するときに読み込み、作業を行います。

Minimaの場合、Jekyllのサイトディレクトリでは以下のファイルだけが見えます。

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

GemfileとGemfile.lockは、Jekyllのサイトを構築するのに必要なgemの必須バージョンを追跡するために、Bundlerが使用します。

gemベーステーマは、テーマ開発者が使用者に更新を利用可能にするのを簡単にします。更新があるとき、開発者はRubyGemsに更新をプッシュします。

テーマgemを使用している場合、（希望するなら）プロジェクトの全てのgemを更新するには、bundle updateを実行します。bundle update <THEME>の<THEME>にminimaのようなテーマの名前を入れて、テーマgemのみを更新することもできます。開発者が追加や更新した（スタイルシートやインクルード）ファイルが自動でプロジェクトにプルします。

gemベーステーマの目標は、テーマのファイルを取得し直す手間無く更新したり、過度に複雑にすること無く、テーマの利点を享受し、コンテンツの作成に注力することです。

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

Jekyllのテーマはデフォルトのレイアウトやインクルド、スタイルシートを設定します。しかし、サイトのコンテンツでテーマのデフォルトを上書きすることができます。

テーマのレイアウトやインクルードを置き換えるには、あなたの_layoutsや_includesディレクトリに修正するファイルをコピーしたり、上書きしたいファイルと同じ名前のファイルを新たに作成します。

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

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

  1. bundle info --pathにテーマgemの名前をつけて実行します。Jekyllのデフォルトテーマなら、bundle info --path minimaです。 これは、gemベーステーマのファイルの場所を返します。例えばmacOSなら、Minimaテーマのファイルは、/usr/local/lib/ruby/gems/2.6.0/gems/minima-2.5.1にあるはずです。

  2. FinderやExplorerでテーマのディレクトリを開きます。

    # 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/2.7.1/gems/minima-2.5.1
#
# then invoke explorer with above path, substituting `/` with `\`
explorer C:\Ruby26-x64\lib\ruby\gems\2.7.1\gems\minima-2.5.1

# On Linux
xdg-open $(bundle info --path minima)

    FinderやExplorerが開き、テーマのファイルやディレクトリが表示されます。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サイトのディレクトリに同じ名前のファイルを作成します。

Minimaのフッターを上書きしたい例です。Jekyllサイトに_includesフォルダを作り、footer.htmlというファイルを追加します。これで、JekyllはMinimaテーマのfooter.htmlではなく、あなたのサイトのfooter.htmlを使用するようになります。

スタイルシートを修正する場合はもう一つステップが必要で、メインのsassファイル（Minimaテーマの場合は_sass/minima.scss）もサイトのソースの_sassディレクトリにコピーします。

Jekyllは以下のフォルダへのリクエストがあったときは、テーマのデフォルトを探す前に、まずサイトのコンテンツを探します。

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

テーマのファイルのコピーを作成すると、それらの更新を受け取れなくなります。テーマの全てのスタイルシートの更新を受け取りたい場合、あなた自身のCSSセレクタを追加し、別名のCSSファイルを使用するとよいでしょう。

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

gemベーステーマから通常のテーマへの変換

gemベーステーマを取り除き、全てのファイルがテーマgemでは無く、Jekyllサイトディレクトリにある通常のテーマに、切り替えたいとします。

これを行うには、テーマ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

もしくは、JekyllプラグインとしてGemfileに記載し、_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テーマを検索すると、他の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.5"を好きなように書き換えてください。

    # ./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つのテーマだけが選択されます。{: .note .info }

JekyllサイトをGitHub Pagesで公開している場合、GitHub Pagesはいくつかのgemベーステーマしかサポートしていないことに注意してください。GitHub Pagesはremote_theme設定で、gemベーステーマならGitHubがホストのテーマの使用をサポートしています。

gemベーステーマの作成

あなたが（テーマの使用者というよりも）開発者なら、あなたのテーマをBundlerを通じユーザーがインストールできるように、RubyGemsにパッケージにすることができます。

Ruby gemsの作成になれていなくても、心配しないでください。Jekyllはnew-themeコマンドで新しいテーマの骨組みを作成します。テーマ名を引数にして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があり、ページのfront matterにlayout: pageがあれば、Jekyllはまずサイトの_layoutsフォルダにpageがあるかを確認し、無ければテーマのpageレイアウトを使用します。

Assets

/assetsフォルダのファイルは、同じ相対パスのファイルが無ければ、ユーザーがサイトを構築するときにコピーされます。SCSS、画像、Webフォントなどを出荷することができます。これらのファイルは、Jekyllに静的ファイルの様に取り扱われます。

  • ファイルの冒頭にfront matterがある場合、レンダリングされます。
  • front matterが無い場合、単純にサイトにコピーされます。

これにより、テーマの作成者は/assets/styles.cssを出荷することが可能になり、レイアウトで/assets/styles.cssを使用できます。

サイトでJekyllを使用しているのと同じように、/assets内のファイルは、作成されたサイトの/assetsフォルダにコピーされます。

Stylesheets

テーマのスタイルシートは、Jekyllサイトを作成するときと同じように、テーマの _sassフォルダに入れます。

_sass
└── jekyll-theme-awesome.scss

テーマのスタイルシートは@importを使用することでダイレクトにユーザーのスタイルシートを取り込めます。

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

テーマgemの依存関係3.5.0

サイトの設定ファイルにpluginsとして明示されていなくても、テーマgemのホワイトリストのruntime_dependenciesを、Jekyllは自動的に必要とします。（注：ホワイトリストは--safeオプションで提供するとき、構築するときのみ必要です。）

これにより、エンドユーザーはテーマgemが機能するように、設定ファイルに含めたプラグインを追跡する必要がありません。

テーマgemの事前設定4.0

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

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

  • Jekkyllのデフォルト設定はテーマの設定で上書きできません。権限はまだ、ユーザーにあります。
  • テーマの設定ファイルは、safe modeやシンボリックリンクが指すファイルがテーマgem内の正当なファイルであるかどうかにかかわらず、シンボリックリンクはできません。
  • テーマの設定は一連のキーと値のペアでなければなりません。空の設定ファイル、キーの下の項目を単にリストする設定ファイル、または単純なテキスト文字列を含む設定ファイルは、単に黙って無視されます。この矛盾に関する警告やログ出力は表示されません。
  • 全てのテーマ設定ファイルの内容は、ユーザーが上書き可能です。

この機能はテーマをより簡単に採用できるようにするためのものですが、制限によってテーマ設定が適切な方法でビルドに影響を及さないようにします。テーマに必要なすべてのプラグインはユーザーが手動でリストするか、テーマの gemspecファイルで提供されなければなりません。

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

テーマのドキュメンテーション

テーマには、テーマのインストールや使用法を伝えるための/README.mdファイルを含めるべきです。どんなレイアウト、どんなファイルが含まれていますか？　使用者はサイトの設定ファイルに何か特別なことを書き加えなければなりませんか？

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

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

テーマのプレビュー

著者としてテーマのプレビューを行うには、/index.htmlや/page.htmlのダミーコンテンツを追加するのが便利です。jekyll buildやjekyll serveをプレビューのために利用できるようになります。あとは、Jekyllサイトのプレビューを行うだけです。

ローカル環境でテーマのプレビューを行ったら、テーマを配布するときにコンパイル済みのサイトが含まれないように、テーマの.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のステップを繰り返してください。テーマバージョンを上げながら、Semantic Versioningに従うことをお勧めします。