Skip to main content

GitHub PagesとJekyllについて

Jekyllは、GitHub Pagesのサポートが組み込まれている静的サイトジェネレータです。

GitHub Pagesは、GitHub Free及びOrganizationのGitHub Freeのパブリックリポジトリ、GitHub Pro、GitHub Team、GitHub Enterprise Cloud、GitHub Enterprise Serverのパブリック及びプライベートリポジトリで利用できます。 詳細については、「GitHub's products」を参照してください。

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 を更新していれば、確実に最新のバージョンを使用できます。 詳細については、GitHub Pages サイトの「Jekyll を使用して GitHub Pages サイトをローカルでテストする」と「依存関係のバージョン」を参照してください。

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

構文の強調表示

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

デフォルトでは、サイトのコードブロックはJekyllによって強調表示されます。 Jekyll は、Rouge ハイライターを使用します。これは Pygments と互換性があります。 Pygmentsは非推奨になっており、Jekyll 4ではサポートされていません。 _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 Enterprise Cloud 上ではなくローカルで変更を行うことができます。 そしてサイトをローカルでテストしてください。 詳細については、「Jekyll を使用して GitHub Pages サイトをローカルでテストする」を参照してください。