GitHub PagesとJekyllについて

Jekyllについて

Jekyllは、GitHub Pagesに組み込まれている静的サイトジェネレータで、ビルドプロセスを容易化できます。 JekyllはMarkdownおよびHTMLファイルを取り込み、選択したレイアウトに基づいて、完成された静的ウェブサイトを作成します。 Jekyllは、Markdownと、サイトに動的コンテンツを読み込むテンプレート言語のLiquidをサポートします。詳細については、「Jekyll」を参照してください。

Windows は、Jekyll を公式にはサポートしていません。詳細については、Jekyll ドキュメントの「Jekyll on Windows」を参照してください。

GitHub Pages ではJekyllを使用することをおすすめします。お好みに応じて、別の静的サイトジェネレータを使用することも、ローカルまたは別のサーバーにおけるビルドプロセスをカスタマイズすることもできます。詳しくは、「GitHub Pages について」を参照してください。

GitHub PagesサイトでJekyllを設定する

_config.yml ファイルを編集することにより、サイトのテーマやプラグインなど、Jekyll の設定のほとんどを構成できます。詳細については、Jekyll ドキュメントの「Configuration」を参照してください。

一部の設定は、GitHub Pagesサイトで変更できません。

lsi: false
safe: true
source: [your repo's top level directory]
incremental: false
highlighter: rouge
gist:
  noscript: false
kramdown:
  math_engine: mathjax
  syntax_highlighter: rouge

デフォルトでは、Jekyllでは以下に当てはまるファイルやフォルダをビルドしません。

/node_modules または /vendor フォルダーに配置されている
_、.、または # で始まる
~ で終わる
構成ファイルの exclude 設定によって除外される

これらのファイルの中に Jekyll で処理したいものがある場合、構成ファイルの include 設定を利用できます。

フロントマター

サイト上のページやポストに対してタイトルやレイアウトといった変数やメタデータを設定するには、任意のMarkdownあるいはHTMLファイルの先頭にYAMLフロントマターを追加できます。詳しくは、Jekyll のドキュメントの「フロントマター」をご覧ください。

投稿またはページに site.github を追加して、あらゆるリポジトリ参照メタデータをサイトに追加できます。詳細については、Jekyll メタデータのドキュメントの「Using site.github」を参照してください。

テーマ

JekyllのテーマをGitHub Pagesサイトに追加して、サイトのルックアンドフィールをカスタマイズできます。詳細については、Jekyll ドキュメントの「Themes」を参照してください。

GitHub で、サポートされているテーマをサイトに追加できます。詳しくは、GitHub Pages サイトの「サポートされているテーマ」と、「Jekyll を使用して GitHub Pages サイトにテーマを追加する」をご覧ください。

GitHub でホストされている他のオープンソースの Jekyll テーマを使うには、テーマを手動で追加できます。詳しくは、GitHub でホストされているテーマに関するページと、「Jekyll を使用して GitHub Pages サイトにテーマを追加する」をご覧ください。

テーマのファイルを編集することで、テーマのデフォルトを上書きできます。詳しい情報については、テーマのドキュメンテーションおよび Jekyll ドキュメンテーションの「Overriding your theme's defaults」を参照してください。

プラグイン

Jekyllプラグインをダウンロードまたは作成すると、サイトでJekyllの機能を拡張できます。たとえば、jemoji プラグインを使うと、GitHub っぽい絵文字を、GitHub で使うのと同じように、サイトの任意のページで使用できます。詳細については、Jekyll のドキュメントの「Plugins」(プラグイン) を参照してください。

GitHub Pagesで使用されるプラグインはデフォルトで有効になっており、無効にすることはできません。

追加のプラグインは、_config.yml ファイルでそのプラグインの gem を plugins 設定に追加すると有効にできます。詳細については、Jekyll ドキュメントの「Configuration」を参照してください。

サポートされているプラグインのリストについては、GitHub Pages サイトで「依存関係のバージョン」を参照してください。特定のプラグインの使い方については、そのプラグインのドキュメンテーションを参照してください。

ヒント: GitHub Pages gem を更新していれば、確実に最新のバージョンを使用できます。詳しくは、「Jekyll を使用して GitHub Pages サイトをローカルでテストする」と、GitHub Pages のサイトの「依存関係のバージョン」をご覧ください。

GitHub Pagesは、サポートされていないプラグインを使用してサイトをビルドすることはできません。サポートされていないプラグインを使用するには、ローカルでサイトを生成してから、サイトの静的ファイルをGitHubにプッシュできます。

構文の強調表示

サイトを読みやすくするには、GitHubで強調表示されるのと同じように、GitHub Pagesサイトでコードスニペットを強調表示します。 GitHub での構文の強調表示について詳しくは、「コードブロックの作成と強調表示」をご覧ください。

デフォルトでは、サイトのコードブロックはJekyllによって強調表示されます。 Jekyll は、Rouge ハイライター (これは Pygments と互換性があります) を使用します。 _config.yml ファイルで Pygments を指定している場合、代わりにフォールバックとして Rouge が使われます。 Jekyll はこれ以外の構文ハイライターを使用できないため、_config.yml ファイルで他の構文ハイライターを指定すると、ページビルド警告が発生します。詳しくは、「GitHub PagesサイトのJekyllビルドエラーについて」を参照してください。

highlight.js など、他のハイライターを使用したい場合は、プロジェクトの _config.yml ファイルを更新して、Jekyll の構文強調表示を無効にする必要があります。

kramdown:
  syntax_highlighter_opts:
    disable : true

お使いテーマに構文強調表示の CSS が含まれていない場合は、GitHub の構文強調表示 CSS を生成し、プロジェクトの style.css ファイルに追加することができます。

rougify style github > style.css

サイトをローカルでビルドする

ブランチから公開している場合、自分のサイトに加えた変更は、それが該当するサイトの公開元にマージされると、自動的に公開されます。カスタムの GitHub Actions ワークフローから公開している場合、変更はご利用のワークフローがトリガーされるたびに公開されます (通常は既定のブランチへのプッシュによる)。まず変更をプレビューしたいなら、GitHub 上ではなくローカルで変更を行うことができます。そしてサイトをローカルでテストしてください。詳しくは、「Jekyll を使用して GitHub Pages サイトをローカルでテストする」を参照してください。