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で使用されるプラグインはデフォルトで有効になっており、無効にすることはできません。
jekyll-coffeescript
jekyll-default-layout
jekyll-gist
jekyll-github-metadata
jekyll-optional-front-matter
jekyll-paginate
jekyll-readme-index
jekyll-titles-from-headings
jekyll-relative-links
追加のプラグインは、_config.yml
ファイルでそのプラグインの gem を plugins
設定に追加すると有効にできます。 詳細については、Jekyll ドキュメントの「Configuration」を参照してください。
サポートされているプラグインのリストについては、GitHub Pages サイトで「依存関係のバージョン」を参照してください。 特定のプラグインの使い方については、そのプラグインのドキュメンテーションを参照してください。
ヒント: GitHub Pages gem を更新していれば、確実に最新のバージョンを使用できます。 詳しくは、「Jekyll を使用して GitHub Pages サイトをローカルでテストする」と、GitHub Pages のサイトの「依存関係のバージョン」をご覧ください。
GitHub Pagesは、サポートされていないプラグインを使用してサイトをビルドすることはできません。 サポートされていないプラグインを使用するには、ローカルでサイトを生成してから、サイトの静的ファイルをGitHub Enterprise Cloudにプッシュできます。
構文の強調表示
サイトを読みやすくするには、GitHub Enterprise Cloudで強調表示されるのと同じように、GitHub Pagesサイトでコードスニペットを強調表示します。 GitHub Enterprise Cloud での構文の強調表示について詳しくは、「コードブロックの作成と強調表示」をご覧ください。
デフォルトでは、サイトのコードブロックは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 Enterprise Cloud 上ではなくローカルで変更を行うことができます。 そしてサイトをローカルでテストしてください。 詳しくは、「Jekyll を使用して GitHub Pages サイトをローカルでテストする」を参照してください。