GitHub PagesとJekyllについて

ここには以下の内容があります:

• Jekyllについて
• 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で処理したい場合、設定ファイルでincludes設定を利用できます。

フロントマター

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

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

テーマ

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

You can add a theme to your site manually. For more information, see "Supported themes" on the GitHub Pages site and "Adding a theme to your GitHub Pages site using Jekyll."

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

プラグイン

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

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をプラグイン設定に追加すると有効にできます。 詳しい情報については、Jekyllのドキュメンテーションの「Configuration」を参照してください。 サポートされているプラグインのリストについては、GitHub Pagesサイトで「依存関係のバージョン」を参照してください。

特定のプラグインの使い方については、そのプラグインのドキュメンテーションを参照してください。

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

構文の強調表示

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

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