AsciiDocで作成したドキュメントをGitHubPagesでマルチブランチ対応で公開する

はじめに

この記事は、システム開発の内部ドキュメントなどをAsciiDocでドキュメントを作成している場合で、GitHubPagesを利用してドキュメント公開をする際に、運用に困ったことを解決した際のメモです。

困り事とは、何も考えずGitHubPagesだけを利用すると、
特定のブランチのドキュメントしか公開できないということです。

例えば、開発途中ではRv対象のドキュメントもビルドした最終的な姿で確認したいですが、GitHubPagesでは公開できておらずローカルビルドして確認するなどで対応していました。
また、エンハンス開発などを行う際に商用で動いているバージョンのドキュメントと、開発中のドキュメントの両方が同時に公開されていてほしいが片方しか公開できないなどもありました。

そんな、自分の不満を解消しました。

複数ブランチのドキュメントを公開した方法

結論から書きますが、
GitHubPage専用のブランチを用意して、複数ブランチのビルド結果を同時に登録して公開しました。

ブランチとしては上記のようなイメージです。
main から develop を作成したタイミングで、GitHubActionsでドキュメントビルドした結果を gh-pages ブランチへPushします。
feature も同様です。

また feature や develop が削除された場合にはドキュメントは残ってほしくないので、
GitHubActionsで公開済みのドキュメントを削除して gh-pages ブランチへPushします。

ビルド、 gh-pages へのPushなどすべてGitHubActionsで実施します。
以降ではも少し掘り下げて詳細に記載します。

最終的なイメージ

作り方の説明の前に、作るものは最終的にこんなものですというイメージを掲載します。
実際のGitHubPagesは こちら です。

GitHubPagesのTOPページ

ブランチ毎のTOPページ

実際のドキュメントページ

作り方

実際のサンプルリポジトリは、以下です。
https://github.com/takashno/asciidoc-document-sample

開発ブランチのディレクトリ構成の説明

開発ブランチ（main, develop, feature） のディレクトリ構成を簡単に説明します。

root
 |-- .github/workflows
 |    |-- build-and-publish-docs.yaml
 |    `-- delete-branch-maintenance.yaml
 |
 |-- docs …ドキュメント公開部（ただし更新はしない）
 |    |-- branches
 |    |    `-- index_template.html
 |    |-- enable_branches_template.json
 |    `-- index.html
 |
 |-- src/docs/asciidoc …ドキュメント作成部
 |    |-- images
 |    |-- part010_sample 
 |    |    |-- chapter010_overview
 |    |    `-- etc...
 |    |-- attributes.adoc
 |    |-- index.adoc
 |    `-- single.adoc
 |
 |-- .gitignore
 |-- .gitattributes
 |-- build.gradle
 |-- settings.gradle

開発ブランチには、
GitHubPagesで公開するためのHTMLなどのテンプレートは配置するものの、
それ以外は登録を行わず空状態です。

gh-pages ブランチの用意

gh-pages ブランチは、GitHubPagesでドキュメントを公開するためだけのブランチです。
それ以外の用途では一切利用しません。
そのため、mainや他のブランチとは全く関係のないブランチの始点すらも孤立した orphan ブランチとして作成します。

git switch main
git switch --orphan gh-pages

~~ ファイル作成など ~~

git add .
git commit -m "gh-pages init."
git push origin gh-pages

gh-pages ブランチのディレクトリ構成の説明

gh-pages ブランチ のディレクトリ構成を簡単に説明します。

root
 |
 |-- docs …ドキュメント公開部（更新はGitHubActionsでのみ実施）
 |    |-- branches
 |    |    `-- index_template.html
 |    |-- enable_branches_template.json
 |    `-- index.html
 |
 |-- .gitignore
 |-- .gitattributes

gh-pages ブランチにはドキュメント公開部のみを登録します。
.gitignore や .gitattributes など最低限のものは入れておきます。

２つのGitHubActionsのWorkflowを用意

以下の２つのGitHubActions向けのWorkflowを作成します。

1. ドキュメントビルド＆公開
   開発ブランチにPushされたタイミングで、
   ドキュメントをビルドして gh-pages ブランチを更新する
2. 削除ブランチメンテナンス
   開発ブランチが削除されたタイミングで、
   gh-pages ブランチからドキュメントを削除して更新する

1. ドキュメントビルド＆公開

WorkflowのYAMLを掲載しても、わかりづらいソースコード解説になってしまいますので、フローチャートで大体実施していることを表します。
実際のソースは こちら です。

2. 削除ブランチメンテナンス

こちらも同様にフローチャートで表します。
実際のソースは こちら です。

若干作りこんでいる内容

今回の仕組みで若干の作りこみを行っている仕組みがあります。
それは、公開しているブランチのリンクを動的に出したり、削除されたブランチのリンクを動的に消したりする仕組みです。

やっていることはシンプルで、
開発ブランチの公開・削除のタイミングで、ブランチ名とCommitIDを定義したJSONファイルを更新するようにします。
GitHubPagesで公開するHTMLページでは、そのJSONファイルを読み込んで、今公開されているブランチを判定して画面表示します。

ドキュメント公開対象のブランチを管理するJSONは、以下のフォーマットです。

[
  {"name": "main", "commit_id": "48ba62227b5ef45a93a8001ce90b88d1579c295e"},
  {"name": "develop", "commit_id": "48ba62227b5ef45a93a8001ce90b88d1579c295e"},
  {"name": "feature/hoge", "commit_id": "48ba62227b5ef45a93a8001ce90b88d1579c295e"},
  {"name": "end", "commit_id": "end"}
]

Workflowでは、このJSONを編集するための sed による置換が入っています。
少し無理やりですが、ドキュメント公開されているブランチがメンテ不要で自動で更新されるので便利かと思います。
JavaScriptはもう少しキレイに書けるとは思います。

最後に

同様の悩みに対して、自分がアプローチした方法以外にも実現方法があるようには思えます。
Netlifyで同じようなことを実現しているようなWeb記事を見ました。
今回は、GitHubPagesだけで実現しきる方法を考えて、たどり着いたものになります。

もし他にも、簡単に実現できる方法がありましたらコメントいただけると幸いです。