GitHub Pagesでroot・docs以外のディレクトリを公開する

TL;DR

# gitのrootディレクトリでスタート
$ git checkout --orphan gh-pages
$ git rm -rf .
$ git commit --allow-empty -m "Initializing gh-pages branch"
$ git push origin gh-pages
$ git checkout -f main
$ git submodule add -f -b gh-pages $(git config --get remote.origin.url) docs/build/html
$ git branch --show-current
main
$ cd docs/build/html
$ git branch --show-current
gh-pages

GitHub Pagesのセットアップ

今回は、GitHub Pagesのセットアップを行います。
GitHub PagesはGitHubが提供する静的サイトホスティングサービスで、特定のブランチにMarkdownやHTMLファイルをプッシュするだけでウェブサイトとして公開することができます。

今回は例としてdocs/build/htmlを公開対象のディレクトリとします。

以下gitコマンドを順に説明していきます。

$ git checkout --orphan gh-pages
$ git rm -rf .

checkoutで新しいgh-pagesという名前のブランチを作成し、そのブランチに切り替えます。
--orphanオプションは、新たに作成されるブランチが既存のコミット履歴を持たないようにするためのものです。
公開するサブモジュールをgh-pagesブランチに切り出すため、mainブランチのコミット履歴は不要です。
checkoutしただけだとファイルをtrackingしている状態なため、rmコマンドで新たに作成したgh-pagesブランチ上のすべてのファイルとディレクトリを削除します。

$ git commit --allow-empty -m "Initializing gh-pages branch"
$ git push origin gh-pages

空のコミットを作成しpushします。

$ git checkout -f main

元のmainブランチに戻ります。
-fオプションは、変更を破棄して強制的にブランチを切り替えるためのものです。

$ git submodule add -f -b gh-pages $(git config --get remote.origin.url) docs/build/html

gh-pagesブランチをdocs/build/htmlというサブモジュールとして追加します。
これによりmainブランチからgh-pagesブランチの内容を参照・更新することができます。

$ git branch --show-current
main

現在いるパスがgitのrootで、現在のブランチがmainであることを確認します。

$ cd docs/build/html
$ git branch --show-current
gh-pages

サブモジュールディレクトリに移動し、そのディレクトリ内で現在のブランチがgh-pagesであることを確認します。

以上で、mainブランチのdocs/build/htmlディレクトリをgh-pagesブランチとして切り出すことができました。
gh-pagesブランチの内容は、https://<username>.github.io/<repository>/で公開されるため、docs/build/htmlディレクトリでHTMLファイルをpushすればそのHTMLファイルがホスティングされます。

解説

この状態でdocs/build/htmlディレクトリを更新すると、gh-pagesブランチの内容も更新されます。
また、gh-pagesブランチの内容を更新すると、mainブランチのdocs/build/htmlディレクトリの内容も更新されます。
このように、mainブランチとgh-pagesブランチの内容を同期できます。