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

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

## やりたいこと

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

![deploy_retitle.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/624259/84af2703-238e-bcfe-8703-8037bb217c0d.png)


# 2. 参考ページ 
- [mike](https://opensourcelibs.com/lib/mike), [mike(github)](https://github.com/jimporter/mike)
  - 今回紹介するMkDocsのプラグイン。MkDocsで静的に生成されるページ内でそのサイトの版切り替えを実現できるプラグインです。
- [MkDocs+plugin:mkdocs-static-i18nで多言語対応サイトを構築する](https://qiita.com/tomoten/items/26706f2eafe84f70b1a6)
  - 本ページで使うMkdocs文書の素材として再利用します。ただし、Githubの別リポジトリで構築するので本ページの検討内容のみでmikeの利用ができるように努めます。
- [VSCode + Remote Container でtypescriptの開発環境を試す](https://qiita.com/tomoten/items/dd83f60bafe716680653)
  - 過去に自分で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](https://github.com/tomoten-umino/my-mkdocs-mike)
- Github Pages : [https://tomoten-umino.github.io/my-mkdocs-mike/](https://tomoten-umino.github.io/my-mkdocs-mike/)

## 3.3. Gitリポジトリの開発環境の使い方
### 3.3.1. ディレクトリ構成

```bash
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を開きます。

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

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

```bash
（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のみコミットします。

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

## 4.3. mikeを使ってみる
※ほぼ、[mike](https://opensourcelibs.com/lib/mike)のREADME通りです。

### 4.3.1.mkdocsへの組み込み
- mkdocs.ymlに以下のように追加します。

```yaml
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で確認することができます。

```bash
# バージョン名: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でビルドした成果物がコミットされるからです。

```bash
$ git checkout gh-pages

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

$ git ckeckout 元のブランチ
```

![deploy_local_1st.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/624259/4dd8e95f-88e5-2c3e-d082-1dc67d573b86.png)

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

```bash
$ 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.
```

![deploy-1.0.0.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/624259/98819c94-d270-48d5-f8b4-c52bb1aeda09.png)

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

```bash
# 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
```

![deploy_retitle.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/624259/84af2703-238e-bcfe-8703-8037bb217c0d.png)

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

```bash
$ 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/](https://tomoten-umino.github.io/my-mkdocs-mike/)となります。

```bash
$ git checkout gh-pages

$ git push origin gh-pages
```

## 5.2. Github Actions連携
長くなるので、「[Github Actions でGithub Pages更新用ビルド、プルリクを自動化する（mkdocs mike利用）](https://qiita.com/tomoten/items/8550315e2c0f1563ad12)」で記述します。

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