Github Pagesの公開ページの版管理（MkDocs plugin mike利用）

1. はじめに

• MkDocsがかなり便利なのでいろいろと使い方を検討してたところ、Github Pagesで表示できるサイトが１つしかない、ことに不便さを感じました。
• Github Pagesの表示サイトの版切り替えがしたいと思っていました。（猛烈に過去のページが見たくなるときがあります。。。）
  • Github Pagesのgh-pages以下に入れ子で複数サイト格納しておけば、表示するURLを切り替えれば表示できることはできます。ただし、いちいちURLを切り替えるのが面倒でした。
• 調査するなかで、mkdocsのプラグイン「mike」が使えそうだったので、その試使用した内容をまとめたいと思います。

やりたいこと

• Github Pagesの公開ページ内で、版の切り替えができるようにします。（最終的に、下図のような感じ）

2. 参考ページ

• mike, mike(github)
  • 今回紹介するMkDocsのプラグイン。MkDocsで静的に生成されるページ内でそのサイトの版切り替えを実現できるプラグインです。
• MkDocs+plugin:mkdocs-static-i18nで多言語対応サイトを構築する
  • 本ページで使うMkdocs文書の素材として再利用します。ただし、Githubの別リポジトリで構築するので本ページの検討内容のみでmikeの利用ができるように努めます。
• VSCode + Remote Container でtypescriptの開発環境を試す
  • 過去に自分でdevcontainerを利用したときのメモ

3. 動作環境

3.1. ローカルの開発環境

• OS : Ubuntu 20.04
• CPU : Intel(R) Pentium(R) CPU G4560 @ 3.50GHz
• RAM : 8GB
• Software
  • docker : 20.10.5
  • docker-compose : 1.24.1
  • VSCode : 1.59.0

3.2. gitリポジトリ

• Gitリポジトリ：https://github.com/tomoten-umino/my-mkdocs-mike
• Github Pages : https://tomoten-umino.github.io/my-mkdocs-mike/

3.3. Gitリポジトリの開発環境の使い方

3.3.1. ディレクトリ構成

my-mkdocs-mike
├── .devcontainer
│   └── devcontainer.json
├── .github
│   └── workflows
│       └── mkdocs-deploy.yml
├── Dockerfile
├── LICENSE
├── README.md
├── docker-compose.yml
├── docs
│   ├── index.ja.md
│   ├── index.md
│   └── topic1（中身は省略。参考ページ[2]参照。）
├── mkdocs.yml
├── requirements.txt
└── site

• .devcontainerはdevcontainerの設定ファイル
• .github以下は、Github Actionsのyml
• Dockerfile, docker-compose.ymlはdevcontainer関連のdockerファイル
• requirements.txtは、pipでライブラリをインストールするときのリスト

3.3.2. devcontainerの起動

4章で利用するまでの準備を記載します。

• Gitリポジトリをcloneします。その後、my-mkdocs-mike以下に移動し、VS Codeを開きます。

(ホスト側で)
$ git clone https://github.com/tomoten-umino/my-mkdocs-mike.git
$ cd my-mkdocs-mike
$ code .

• VSCode左下にある「＞＜」みたいなボタンを押下して、「Reopen in Container」を押下します。
  • python3のdevcontainerが起動します。
• VSCode内でリモート接続中のコンテナ内のターミナルを開き、pipで必要なツールをインストールする。

（devcontainer内）
$ pip install -r requirements.txt

4. mikeの使い方

4.1. 肝なところ

• mkdocsは、mkdocs buildとするとsiteディレクトリ以下に公開する静的ページが生成されます。
• mikeを使うと、gh-pagesブランチの直下に、ビルド時に指定するバージョン名ディレクトリを作成し、その中に公開する静的ページが生成されます。
  • mikeのビルドするブランチと、保存されるブランチ(gh-pages)が異なります。

4.2. mikeを使う前の準備

• gh-pagesブランチが無い場合、事前に作成しておきましょう。
  • 公開しているGitブランチは、すでにgh-pagesが作成されています。
  • gh-pagesブランチを作成するとき、--orphanオプションをつけると、無駄なファイルを登録せずに済みます。
    • その場合、gh-pagesを作成したときにもともとあったファイルがgit addされた状態になるので、不要なものをgit resetで取り除く必要がある。私は、.gitignoreのみコミットします。

$ git checkout --orphan gh-pages
$ git reset 不要なもの
$ git commit -m "コミットメッセージを適当に"
$ git push origin gh-pages

4.3. mikeを使ってみる

※ほぼ、mikeのREADME通りです。

4.3.1.mkdocsへの組み込み

• mkdocs.ymlに以下のように追加します。

plugins:
  - mike:
      version_selector: true
      css_dir: css
      javascript_dir: js
      canonical_version: null

4.3.2. デプロイする

-　mike deploy バージョン名でデプロイを実行できます。

• コマンドは、gh-pagesブランチ以外のブランチで実施すること。静的サイトはsiteディレクトリ以下に生成されるのに合わせ、gh-pagesブランチにもコミットされます。
• デプロイした内容は、mike serveコマンドを実行することで、簡易web serverを起動して確認できます。
  • mike serveでは、gh-pages直下の内容を簡易web serverで確認することができます。

# バージョン名:0.0.1でデプロイ
$ mike deploy 0.0.1
mike deploy 0.0.1
INFO     -  Adding 'ja' to the 'plugins.search.lang' option
INFO     -  Cleaning site directory
INFO     -  Building documentation to directory: /workspace/site
INFO     -  Building en documentation
INFO     -  Building ja documentation
INFO     -  Translating navigation to ja
INFO     -  Documentation built in 2.63 seconds

$ mike serve
Starting server at http://localhost:8000/
Press Ctrl+C to quit.

• ブラウザでhttp://localhost:8000/にアクセスすると、何も表示されません…。
• ブラウザでhttp://localhost:8000/0.0.1にアクセスすると、以下のように表示されます。
  • これは、gh-pagesブランチのルート直下でlsするとわかりますが、0.0.1というディレクトリが生成され、その中にmike deployでビルドした成果物がコミットされるからです。

$ git checkout gh-pages

$ ls -1
0.0.1   <- ここに入っている
site
versions.json

$ git ckeckout 元のブランチ

• 再度、mike deployでデプロイします。このとき、1.0.0 (stable版)とすることにします。
• mike serveで簡易web serverを起動し、ブラウザでhttp://localhost:8000/0.0.1にアクセスすると、以下のように表示されます。
  • 上部のバージョン番号のところで、切り替えすることができます。

$ mike deploy 1.0.0 stable
INFO     -  Adding 'ja' to the 'plugins.search.lang' option
INFO     -  Cleaning site directory
INFO     -  Building documentation to directory: /workspace/site
INFO     -  Building en documentation
INFO     -  Building ja documentation
INFO     -  Translating navigation to ja
INFO     -  Documentation built in 1.42 seconds

$ mike serve
Starting server at http://localhost:8000/
Press Ctrl+C to quit.

• この状態では、1.0.0がstable版だとわかりにくいので、表示タイトルにstableと表示することにします。mike retitleコマンドを用いて、バージョン名に修正を加えます。
• その後、mike serveで簡易web serverを起動し、ブラウザでhttp://localhost:8000/0.0.1にアクセスすると、バージョン名が1.0.0_stableと表示されることが確認できます。

# mike listで現在登録されている版リストが表示される。
$ mike list
1.0.0 [stable]
0.0.1

$ mike retitle 1.0.0 1.0.0_stable

$ mike list
"1.0.0_stable" (1.0.0) [stable]
0.0.1

• 上記では、ページアクセスの際に0.0.1など、バージョン名を入力してアクセスしていましたが、http://localhost:8000/にアクセスしたときに表示されるデフォルトページは設定しておきたいです。そのときは、mike set-defaultコマンドを利用してデフォルト表示するバージョンを設定します。
  • デフォルトページを設定すると、http://localhost:8000/にアクセスすると指定したバージョンへリダイレクトする挙動となります。

$ mike set-default stable

5. Github Pagesでの公開

5.1. ローカルで操作した内容を直接pushする

• mikeコマンドを実行すると、その実行結果がgh-pagesブランチにコミットされるので、gh-pagesブランチをリモートのGithubにpushすればよいです。
  • Github Pagesは、別途公開する設定にしてください。
• 本記事で作成したPagesは、https://tomoten-umino.github.io/my-mkdocs-mike/となります。

$ git checkout gh-pages

$ git push origin gh-pages

5.2. Github Actions連携

長くなるので、「Github Actions でGithub Pages更新用ビルド、プルリクを自動化する（mkdocs mike利用）」で記述します。

6. おわりに

• 公開しているGithub Pages内で複数のバージョン切り替えができるのは便利に感じました。
  • 例えば、API仕様書等をMkDocsで作成したとして、A版とB版を確認したい、といった場合に、切り替えしながら中身を確認できることになります。
• Github Actionsに関しては、次記事にて記載します。master更新時に随時devページ更新、tag打ちしたタイミングで版更新する等の運用検討が必要なので、その部分の検討から記載する予定です。