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

GitHub リポジトリにファイルを入れ、そのまま Web サイトとして公開できます。
HTML などの静的ファイルをコミット git push して公開する方法は知られていますが、
もっと容易に Web サイトを制作・公開できる仕組みがあります。

運営者がいくつかのテーマを日本語解説付きで公開しています。

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


目次


公式サイト


使用制限・禁止用途

 使用制限 | GitHub ヘルプ

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

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

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

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

一言でいうと、営利目的とした利用は禁止です。
ただし会社の利用を禁じているわけではありません。
会社組織がオープンソースの公開を目的をしているなどは問題ありません。

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


使用方法

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 などを含めます。

運営者は GitHub ユーザー fu-sen で使用しているので、 fu-sen.github.io です。が、
独自ドメインを割り当ててあります。  個人組織ページに独自ドメインを割り当てる

 fu-sen/fu-sen.github.io | GitHub
🎈 fu-sen.github.io

また、Organization remotetheme で使用しているので、 remotetheme.github.io もあります。

 remotetheme/remotetheme.github.io | GitHub
🎈 remotetheme.github.io

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

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

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

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

運営者はリポジトリで fu-sen.github.io のファイル CNAME で
fu-sen.bal.gdn を設定してあります。

 CNAME | GitHub fu-sen/fu-sen.github.io

そのため、fu-sen.github.io は fu-sen.bal.gdn へ転送されます。

🎈 fu-sen.bal.gdn

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


Jekyll

GitHub Pages ではバックエンドに静的サイトジェネレータ Jekyll が採用されています。
テーマを詳細に編集したり、ローカルで動作確認を行いたい場合や、
GitHub Pages 外の Web サービスを使用したい場合はこちらを参照して下さい。

 Jekyll
🎈 Jekyll | ふうせん🎈 FU-SEN


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 を使用できます。

JS.ORG でもこの問題が発生します。

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

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

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

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

 GitHub Actions

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

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