GitHub Pages

GitHub Pagesは、ユーザー、組織、リポジトリの公開Webページで、github.ioかカスタムドメイン名を選択でき、GitHubにホストされています。GitHub PagesはJekyllによって供給されているので、無料でJekyllで運営されているWebサイトをホストするのに最適な方法です。

ソースファイルをプッシュすると、GitHub Pagesによりサイトが自動で生成されます。GitHub Pagesは通常のHTMLコンテンツでも同様に機能します。理由は簡単で、Jekyllはfront matterの無いファイルは静的なassetとして扱うためです。生成されたHTMLをプッシュするのでしたら、更なる設定を何もせずに行えばいいです。

GitHub Pagesでサイトを構築するのは初めてですか? Jonathan McGloneによる素晴らしいガイドを見て、行ってみてください。このガイドでは、GitHub Pagesで自身のWebサイトを作るために、GitやGitHub、Jekyllについて知っておくべきことを説明しています。

The github-pages gem

GitHubの友人たちは、JekyllとそのGitHub Pagesへの依存関係を管理するために使用されるgithub-pagesを提供しています。プロジェクトでそれを使うことは、サイトをGitHub Pagesにデプロイするとき、gemの様々なバージョン間の予想外の違いに捕まることはないということを意味します。

GitHub Pagesはsafeモードで動作し、ホワイトリストに登録されたプラグインのセットのみを許可していることに気をつけてください。

プロジェクトで現在デプロイされているバージョンのgemを使用するには、Gemfileに以下を追加します。

source "https://rubygems.org"

gem "github-pages", group: :jekyll_plugins

必ずbundle updateを頻繁に実行してください。

GitHub Pagesのドキュメンテーションとヘルプ、サポート

GitHub Pagesでできることやトラブルシューティングガイドの詳細については、GitHubのPagesヘルプセクションをご覧ください。 それでもうまくいかない場合は、GitHubサポートに連絡してください。

プロジェクトページのURL構成

GitHubにプッシュする前にJekyllサイトをプレビューした方が良い場合があります。GitHubがプロジェクトページに使用するサブディレクトリのようなURL構造は、URLの適切な解決を複雑にします。あなたのサイトが正しく構築されていることを確認するために、便利なURLフィルタを使用してください。

<!-- For styles with static names... -->
<link href="{{ "/assets/css/style.css" | relative_url }}" rel="stylesheet">
<!-- For documents/pages whose URLs can change... -->
[{{ page.title }}]("{{ page.url | relative_url }}")

この方法で、localhost上のサイトrootからローカルでプレビューできます。そして、GitHubがページを生成するときには、全てのURLが正しく解決されます。

JekyllをGitHub Pagesにデプロイ

GitHub PagesはGitHub上のリポジトリの特定のブランチを見ることによって機能します。利用可能な2つの基本的な種類があります:user/organization と project pages。これら2種類のサイトを展開する方法は、いくつかの細かい点を除いてほぼ同じです。

UserとOrganizationページ

UserとOrganizationページは、GitHub Pagesのファイル専用の特別なGitHubリポジトリにあります。このリポジトリは、アカウント名にちなんで命名する必要があります。たとえば、@mojomboのユーザーページのリポジトリの名前はmojombo.github.ioです。

GitHub Pagesサイトの構築と公開には、リポジトリのmasterブランチのコンテンツが使用されます。そのため、Jekyllサイトがそこに格納されていることを確認してください。

カスタムドメインはリポジトリ名に影響しません

GitHub Pagesは、まずusername.github.ioサブドメインの下に存在するように設定されています。そのため、カスタムドメインを使用している場合でも、リポジトリにこのように名前を付ける必要があります。

Project Pages

UserとOrganizationページとは異なり、プロジェクトページは、目的のプロジェクトと同じリポジトリに保存されます。ただし、Webページのコンテンツは、特別な名前のgh-pagesブランチ、またはmasterブランチのdocsフォルダに格納されているます。コンテンツはJekyllを使用してレンダリングされ、出力はusername.github.io/projectなどのユーザーページサブドメインのサブパスの下に表示されます(カスタムドメインが指定されていない場合)。

Jekyllプロジェクトのリポジトリ自体が、このブランチ構造の完璧な例です。マスターブランチ にはJekyllの実際のソフトウェアプロジェクトが含まれています。現在見ているJekyll Webサイトは、同じリポジトリのdocsフォルダにあります。

より詳細な例については、GitHubの公式ドキュメントのuser, organization and project pagesを参照してください。

ソースファイルはrootディレクトリに必要です

GitHub Pagesは“Site Source”の設定値を上書きするため、ファイルをルートディレクトリ以外の場所に配置すると、サイトが正しく構築されない可能性があります。

Windowsでのgithub-pages gemのインストール

Windowsは公式にサポートされていませんが、Windows上にgithub-pages gemをインストールすることは可能です。詳細はWindowsの特別なページをご覧ください。