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 Pages サイトの「サポートされているテーマ」と、「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 Serverにプッシュできます。

構文の強調表示

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

デフォルトでは、サイトのコードブロックは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 Enterprise Server 上ではなくローカルで変更を行うことができます。そしてサイトをローカルでテストしてく� さい。詳細については、「Jekyll を使用して GitHub Pages サイトをローカルでテストする」を参照してく� さい。