リポジトリへコミットし Web 公開できる GitHub Pages(ギットハブ ページ)についてまとめています。

GitHub リポジトリにファイルを入れ、そのまま Web サイトとして公開できます。


目次


公式サイト


使用制限・禁止用途

 使用制限 | GitHub ヘルプ

GitHub Pages は次の制限があります。

  • リポジトリ・公開サイトの容量: 1GB
  • 転送量: 月 100GB
  • ビルド: 1 時間 10 ビルド

これらはソフト制限で、これらを超えた場合は通知が届きます。

 禁止される用途 | GitHub ヘルプ

禁止される用途
GitHub Pages は、オンラインビジネス、eコマースサイト、主に商取引の円滑化またはサービスとしての商用ソフトウェアの提供 (SaaS) のどちらかを目的とする、その他のウェブサイトを運営するための無料のウェブホスティングサービスとしての使用を意図したものではなく、またそのような使用を許可するものでもありません。

通常 GitHub Pages は無料でソースを含めて公開されるので、
有料販売されるソフトウェアを GitHub Pages で公開してしまうと
支払いする事なく、ダウンロードできてしまう事になります。
有料向けはそれに適した Web サービスを使って下さい、という事でしょう。

これは法人での使用を禁止しているわけではありません。
法人用途でもフリーソフトのソースなどを公開する目的であれば
GitHub Pages を使っても構わない事になります。
またこの禁止用途は GitHub Pages なので、
GitHub そのものを禁止するものではありません。
例えば GitHub リポジトリで Web サイトのソース管理を行い、
そこから他のサービスでビルド・デプロイして公開する場合は
有料向けで使用しても良い事になります。

他にも禁止事項があります。


使用方法

GitHub リポジトリへの git push で使うのが通例ですが、
GitHub の Web 上でリポジトリを生成し、ファイルの作成・編集する事ができますので、
必ずしも Git の扱いに慣れている必要があるわけではありません。

ファイル

HTML などを入れてそのまま公開できます。
また、🎈 Markdown を代わりに使用できます。.md ファイルを使用します。
ただし。GitHub のソース表示とは異なる解釈をするものがあります。
.md ファイル内で HTML の記載も可能です。.html ファイルの混在も可能です。

index.html はファイル名の省略で表示できますが、
Markdown は index.md を使用できます。
またこれらがない場合、プロジェクトページで表示される README.md が使われます。
ページの最小限は index.html・index.md・README.md のみとなります。

Not Found は 404.html および 404.md が表示されます。

ファイル.html は ファイル でも参照できます。
ファイル.md は ファイル.html または ファイル でも参照できます。
ファイル/ は物理的にディレクトリ(フォルダ)となり、参照できません。

独自ドメインを設定した場合は、ファイル CNAME が生成され、
その中に ドメイン名 が入ります。

_config.yml はテーマや title などのサイト全体の設定に使われます。
正しくは Jekyll の設定ファイルです。
Jekyll は GitHub Pages に組み込まれている静的サイトジェネレータです。

GitHub Pages の設定

リポジトリページの Setting を参照し、下へスクロールすると
「GitHub Pages」の項目があります。

以下に各項目を紹介しています。


Source 公開・非公開とブランチの選択

公開するブランチを選択します。公開・非公開のスイッチでもあります。

  • master branch - デフォルトの master ブランチ内をそのまま Web 公開します。
  • master branch /doc folder - doc/ フォルダ内を Web 公開します。
    master ブランチでソースを公開している上で、
    doc/ 内をドキュメント等の目的で Web 公開する事できます。
  • None - GitHub Pages を無効化します。

他のブランチが存在している場合、これらのブランチも一覧に表示されます。
GitHub Pages は当初 gh-pages ブランチを使用する方法が採用されていて、
現在は必須ではなくなっていますが、慣習的に使用しているリポジトリが存在します。


Theme Chooser テーマの適用・選択

シンプルに HTML・Markdown を制作した際、テーマを適用できます。

HTML で適用する場合、.html ファイル内は <body>~</body> 内の内容を入れ、
<head>~</head> の装飾は削除して下さい。
代わりに Front matter で latout: default を加えます。
テーマによって適用する layout を変更する必要があります。

---
layout: default
---

テーマによっていくつかのテーマを適用できます。
主に次のレイアウトで用意されていて、
ブログ および Web サイト どちらでも使用できるようになっています。

  • layout: home - index.md などのトップページ。主にブログの一覧表示です。
  • layout: post - ブログ記事ページ。
  • layout: page - about.md など、記事以外の個別ページ。ブログではない Web サイト。

該当ページの GitHub プロジェクトページより
_layouts/ 内を参照して用意されているレイアウトを確認できます。

.md ファイルでテーマで使用できる項目があれば、
それを .html ファイルでも使用できます。

GitHub Pages 対応テーマ

Settings 内「GitHub Pages」の項目から簡単にテーマを適用できます。
この時テーマの選択とサンプルが表示されますが、
次のページからも参照可能です。

 Supported themes | GitHub Pages

テーマを適用していない場合、Primer がデフォルトテーマとして適用されています。

 pages-themes/primer | GitHun

適用すると _config.yml が生成されます。
_config.yml での設定内容は、ある程度テーマで共通しているところがあります。

lang: ja
title: Example Domain
description: example.net.eu.org
theme: jekyll-theme-slate
show_downloads: true
google_analytics: UA-TRACKING-ID
github:
  is_project_page: false
  zip_url: https://~/file.zip
  tar_url: https://~/file.tar.gz
  repository_url: https://github.com/~
  • themes: jekyll-theme-テーマ名 で統一されています。
  • title: サイト名。ヘッダに大きく表示します。
  • description: 説明。サイト名の下に表示します。
  • show_downloads: true にするとダウンロードリンクを表示します。
  • google_analytics: 設定している場合はトラッキング ID を入れます。
    Google アナリティクス 4(GA4)の 測定 ID は非対応の可能性があります。
  • github: 下層は空白を半角 2 文字以上入れて下さい。
    • is_project_page: false にすると
      プロジェクトページへのリンクが非表示になる場合があります。
    • zip_url: .zip ファイルのダウンロード URL を入れます。
    • tar_url: .tar.gz ファイルのダウンロード URL を入れます。
    • repository_url: 省略するとビルド元のプロジェクトになりますが、変更できます。

テーマによって追加の設定があります。
_layouts/default.html を参照してみて下さい。

 pages-themes | GitHub

他に公開されているテーマ

Theme Chooser 以外でも Jekyll テーマで remote_theme に対応している場合、
_config.yml を生成し、remote_theme を入れるだけでテーマを適用できます。
Jekyll テーマ一覧へのリンクは Jekyll 公式サイトの次から参照できます。

 Resources | Jekyll

指定する値は GitHub リポジトリで remote_theme: ユーザー/リポジトリ です。

例えば Just the Docs は次の GitHub リポジトリで公開されています。

 pmarsceill/just-the-docs | GitHub

従って、 _config.yml に次を追加します。

remote_theme: pmarsceill/just-the-docs

これだけでテーマが適用されます。更にテーマに応じた設定の追加が可能です。
GitHub Pages ではわざわざリポジトリをクーロン・修正する必要はありません。
最小限でファイル管理を行えます。


Custom domain 独自ドメインの適用・設定

独自ドメインを適用します。適用しない場合は次のアドレスになります。

  • https://ユーザー名.github.io/プロジェクト名 - 個人の場合
  • https://組織.github.io/プロジェクト名 - 組織の場合

※ ~.github.com/プロジェクト名 は古い記載で、現在は使用できません。

ファイル CNAME にドメイン名が入った状態で生成されます。
これは Settings で設定せずに CNAME ファイルを作って git push も可能です。

🎈 ネームサーバ は次で設定します。

サブドメイン 種類 値
公開ドメイン名 CNAME 個人・組織.github.io

www などのサブドメインを付けない場合、
CNAME の代わりに ANAME・ALIAS レコードで設定できる場合があります。
これがネームサーバで対応していない場合、A レコードで設定が必要です。

Windows 以外では dig で検索できます。

dig fu-sen.github.io

Web でも検索可能です。Google が提供している dig があります。

 Dig | G Admin Toolbox

「名前」に 個人・組織.github.io を入れて下さい。
レコードは A がデフォルトになっています。

ここでは fu-sen.github.io で実際に検索した結果です。

;QUESTION
fu-sen.github.io. IN A
;ANSWER
fu-sen.github.io. 3599 IN A 185.199.109.153
fu-sen.github.io. 3599 IN A 185.199.108.153
fu-sen.github.io. 3599 IN A 185.199.110.153
fu-sen.github.io. 3599 IN A 185.199.111.153

Windows では代わりに nslookup が使えます。Windows 10 でも使用可能です。

nslookup fu-sen.github.io
権限のない回答:
名前:    fu-sen.github.io
Addresses:  185.199.110.153
          185.199.108.153
          185.199.111.153
          185.199.109.153

この場合、ネームサーバは次の設定になります。

サブドメイン 種類 値
なし・@・ドメイン名 A 185.199.108.153
なし・@・ドメイン名 A 185.199.109.153
なし・@・ドメイン名 A 185.199.110.153
なし・@・ドメイン名 A 185.199.111.153

個人・組織によって IP アドレスが異なります。
必ず dig ・ nslookup で調べた上で設定して下さい。


Enforce HTTPS 常時 SSL の有効化

2016年6月15日以降に生成されたプロジェクトでは
個人・組織.github.io/プロジェクト名 が常時 https 固定になります。

独自ドメインを使用した場合は現在も選択できます。
従って独自ドメインであれば http での公開が現在でも可能です。

SSL 証明書には 🎈 Let’s Encrypt を発行し、有効な間は自動更新されます。
これに最低でも数分要するため、  を入れて参照できるようになるまで数分要します。
発行にはネームサーバが反映されている必要があります。
ネームサーバにはキャッシュ(TTL)がある事にご注意下さい。


個人・組織.github.io で公開する

プロジェクトを後ろに付けない
個人.github.io または 組織.github.io でもページ公開できます。
個人・組織の自己紹介や Blog などの目的で使用できます。

ここでの「組織」は GitHub 上では Organization ・ Team の記載で、
法人用途以外でも設定して使用でき、組織内でプロジェクトを作成できます。
一人での作成も可能ですし、複数人での構成も可能です。
この機能があるため、現在個人で複数のアカウントを持つ事は非推奨になります。

プロジェクト名を 個人.github.io または 組織.github.io で作成するだけです。
その中に index.html などを含めます。

ここに入れた robots.txt は独自ドメインを使用しない
個人・組織.github.io/プロジェクト の Web ページにも影響があります。
また favicon などの画像もプロジェクトで meta タグ指定がない場合は反映されます。
Sitemap にも注意を要します。
この辺の問題を回避するために、プロジェクトに独自ドメインを割り当てたり、
サブドメインを使用できる 🎈 Cloudflare Pages ・ 🎈 Vercel で
Web サイトを公開するのが良いでしょう。

独自ドメインへの転送

プロジェクトに CNAME ファイルを設定した場合、GitHub Pages が有効のままだと
CNAME を設定しない時に機能する 個人・組織.github.io/プロジェクト は
その CNAME の独自ドメインへの転送動作になります。

GitHub Pages は CNAME 記載の独自ドメインも
GitHub Pages で管理される事を期待しますが、
他の Web サービスなどで使用する事もできます。
git push する度にメールで通知が届きますが、実際の動作には問題ありません。

これは参照が多くなり、GitHub Pages の制限に達してしまっても、
従来使用していたアドレスは独自ドメインへの転送にして、
独自ドメインを他の Web サービスで運用する事で、維持できます。

🎈 Cloudflare Pages や 🎈 Surge は転送量の制限がないので候補にできるでしょう。

example.com が CNAME に設定されて使用する GitHub Pages の場合、
www.example.com も GitHub Pages のサーバに設定した場合、
www.example.com は example.com へ転送されます。
逆に www.example.com を CNAME に入れていた場合は、
example.com は www.example.com へ転送されます。

個人・組織ページに独自ドメインを割り当てる

個人ページ・組織ページにも CNAME ファイルを生成し、
独自ドメインを割り当てる事ができます。
(プロジェクト名 ~.github.io は独自ドメインにせず、そのままにします)

CNAME の中身を example.com として独自ドメインを割り当てた場合、
~.github.io を参照すると example.com に転送されあす。
更にその個人・組織によるプロジェクトはそのプロジェクトで CNAME を生成しない場合、
~.github.io/プロジェクト の代わりに example.com/プロジェクト で使用できます。


Q&A

_ ではじまるディレクトリ・ファイルが機能しません。

GitHub Pages では Jekyll を採用していますが、
Jekyll の仕様として _ ではじまるディレクトリ・ファイルを無視します。

対策としてルートに空の .nojekyll を含めて下さい。
これにより Jekyll の動作が無効になります。

GitHub Pages をブログとして使用できますか?

jekyll テーマでブログスタイルに対応したテーマがあります。
例えば運営者公開のサイトから探してみて下さい。

🎈 GitHub Pages テーマ 日本語サンプル (remotetheme.github.io) | GitHub
🎈  GitHub Pages テーマ 日本語サンプル (remotetheme 組織ページ) | GitHub

GitHub Pages で備わっているテーマでは
個々の Markdown ページで公開する前提で作られていて、
ブログの一覧表示を行うように製作されていません。
また、プロジェクトの Web ページと使用する前提のため、
GitHub プロジェクトページや最新版ダウンロードへのリンクが備わっています。

コミットする度にメール通知が届きます。

ネームサーバが設定したての場合や GitHub が推奨するレコード設定をしていない場合に
GitHub からメール通知が届きます。

Subject: [ユーザー/リポジトリ] Page build warning


The page build completed successfully, but returned the following warning for the master branch:

Your site’s DNS settings are using a custom subdomain, ドメイン名, that’s set up as an A record. We recommend you change this to a CNAME record pointing at ユーザー.github.io. For more information, see https://help.github.com/en/articles/using-a-custom-domain-with-github-pages.

For information on troubleshooting Jekyll see:

https://help.github.com/articles/troubleshooting-jekyll-builds

If you have any questions you can contact us by replying to this email.

🎈 EU.org を更なるサブドメインなしの状態で設定した場合、
CNAME・ALIAS・ANAME で設定しても実際には A レコードで設定されるため、
メール通知が届きます。
これを回避するのは他のサービスで Web 公開するようにします。
例えば 🎈 Vercel を使用できます。

プログラミング言語はサーバ動作しますか?

GitHub Pages のサーバ上では非対応です。
(PHP・JavaScript・Ruby・Python・Go など)
🎈 Vercel などを検討して下さい。

他の静的サイトジェネータは使用できますか?

🎈 MkDocs はコマンドを用いた GitHub Pages 向けの公開機能があります。
Git 操作に不慣れな場合でも手軽に公開を行う事ができます。

GitHub Actions を用いる事で
他の静的サイトジェネータのデプロイができる場合があります。

 GitHub Actions

GitHub Pages の代わりに 🎈 Cloudflare Pages ・ 🎈 Vercel を使用する方法もあります。
🎈 Hugo など、多くの静的サイトジェネータに対応しています。

もちろん、ローカルのパソコンなどでデプロイし、静的ファイルを生成した上で、
git push する事も可能です。