GitHub PagesとJekyllについて
Jekyllは、GitHub Pagesのサポートが組み込まれている静的サイトジェネレータです。
GitHub Pages は、GitHub Free のパブリックリポジトリ、GitHub Pro 、GitHub Team、GitHub Enterprise Cloud、GitHub Enterprise Server のパブリックおよびプライベートリポジトリで利用できます。
ここには以下の内容があります:
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 gemを更新していれば、確実に最新のバージョンを使用できます。 詳しい情報については、GitHub Pages サイトの「Jekyll を使用して 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 サイトをローカルでテストする」を参照してください。