GitHub Pages をローカルでテストする (2025)

GitHub Pages はいろいろカスタマイズできるのですが、出来上がるページを確認するのにいちいち git push しないといけないのが作業的にもコミット履歴としてもちょっとよろしくないです。
そこで push する前にローカルでテストする方法を調べました。

作業環境は Windows 10 です。

情報は 2025 年 1 月現在のものです。
環境はどんどん変化していくため、あくまでこの時点の情報であることをご確認ください。

Docker で環境をつくる

環境を Docker で構築します。

Docker ってなんぞや？ってのは調べてください。
調べてもよくわからないかもしれませんが、今回ローカルでテストできるようになるころにはなんとなくその便利さがわかるかと思います。
自分がそうでした。

1. Docker Desktop をインストールする

参考：Windows 11にDocker Desktopを入れる手順（令和5年最新版）

2. GitHub Pages をローカルで作る Docker イメージを取得する

今回は mrseccubus/github-pages イメージを使います。Docker Desktop で取得してください。

3. テストする GitHub Pages のソースを準備する

GitHub Pages のソースとなるディレクトリを用意します。
git のリポジトリディレクトリ、もしくは設定によってはその docs ディレクトリのことです。

例として、以下のように index.md ファイル１つだけの最小構成で考えます。
ローカルでテストするには、さらに2つの設定ファイルが必要です。

C:\Sample
     +- index.md
     +- Gemfile
     +- _config.yml

WSL2 の Ubuntu のファイルシステム上にソースを配置して Ubuntu で作業したほうが少し便利になります。

3.1 Gemfile

このテキストファイルの内容は以下の通りです。

source 'https://rubygems.org'
gem "github-pages", "~> 232", group: :jekyll_plugins

「232」は github-pages のバージョンで、対応するものを指定する必要があります。
Dependency versions から調べて適切な値に変更してください。

3.2 _config.yml

このテキストファイルの内容は以下の通りです。

repository: user/repo
title: Sample
description: This is sample.

すでに _config.yml がある場合はそこに記述してください。

このファイルで GitHub Pages が自動追加する情報をローカルでも動作するように設定しています。
「user/repo」には GitHub のユーザー名、リポジトリ名を指定してください。おそらく生成する URL に使用されます。

4. Docker コンテナを作成して GitHub Pages をローカルで確認する

準備はできました。これらをローカルで変換してブラウザで確認できるように Docker を動かします。

わかりやすいので、コマンドラインで作業します。Docker Desktop がインストールされていればコマンドラインで docker コマンドが使用できます。
作業ディレクトリ (C:\Sample) に移動して、以下のコマンドを実行します。

PowerShell の場合

docker run --volume="$(pwd):/root/project:delegated" --publish 4000:4000 -ti mrseccubus/github-pages 

Ubuntu シェルの場合

docker run --volume="$PWD:/root/project:delegated" --publish 4000:4000 -ti mrseccubus/github-pages

しばらくビルド処理のログが流れたあと、成功すれば以下のメッセージでローカルWebサーバが起動した状態で止まります。

:
Auto-regeneration: enabled for '/root/project'
Server address: http://0.0.0.0:4000
Server running... press ctrl-c to stop.

何らかのエラーが発生した場合、延々とビルドが繰り返されることがあります。このときは Ctrl+C を素早く2回押すことで停止します。

この状態で、Webブラウザで http://localhost:4000 にアクセスして GitHub Pages と同じページが確認できれば成功です。わーい！

このあと index.md を編集してそれを反映させたい場合は Ctrl+C を押してください。再ビルドされるので、その後ブラウザを更新すれば反映されます。

このローカルサーバー (Docker コンテナ) を停止させるには Ctrl+C を素早く2回押してください。

Ubuntu で実行させていると、ファイルが更新されると自動で再ビルドされるようで、ちょっと便利です。

おわりに

以上で最低限の動作確認方法となります。

作業ファイルが作られる、とか、毎回 docker run するとコンテナが増え続ける、とかありますが、別途対処してください。