Material for MkDocsで生成したサイトをGithub Pagesで公開する

MkDocsとは

MkDocksを使うとMarkdownで記載したファイルを元に静的なサイトを生成することができます。

https://www.mkdocs.org/

テーマを選択

サイトを生成するにあたってテーマを利用することで様々なテイストにカスタマイズすることができます。
Read the Docs というテーマがよく利用されていますが他にも色々とあります。
サードパーティのテーマをまとめているページもありますので自分のテイストに合うものを見つけましょう。

https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes

今回は Material for MkDocs というテーマを利用することにします。

https://squidfunk.github.io/mkdocs-material/

mkdocs-material をインストール

作業用ディレクトリを作ってそこに移動します。

仮想環境を用意します。

# 仮想環境作成
$ python3 -m venv .venv

# アクティベート
$ source .venv/bin/activate

mkdocs-material をインストール

pip install mkdocs-material

記事を書く

さっそく記事を書いていきます。
作業用のディレクトリで以下のコマンドを実行します。

mkdocs new .

すると以下のようなファイルが生成されます。

.
├─ docs/
│  └─ index.md
└─ mkdocs.yml

mkdocs.yml を開いてmaterialテーマを適用するための最低限の設定を記載します。

theme:
  name: material

色を変更したい場合はこちらを参照。

あとは docs ディレクトリの下にMarkdownで記述していくだけです。
記事のプレビューは以下のコマンドを打つとできます。

mkdocs serve

デフォルトだとport 8000 で起動しますが指定することもできます。
たとえば 8080 で起動したい場合は以下の通り。

mkdocs serve --dev-addr=127.0.0.1:8080

Mermaid 対応

mkdocs-material は Mermaid 記法にも対応できダイアグラムも埋め込むことができます。
mkdocs.yml に以下のような記載をします。

  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

https://squidfunk.github.io/mkdocs-material/reference/diagrams/

Github Pages で公開する

mainブランチにプッシュしたらGithub Actionsでページが公開されるように設定します。

on:
  push:
    branches:
      - main
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
        with:
          python-version: 3.9
      - run: pip install mkdocs-material
      - run: mkdocs gh-deploy --force

こちらのサンプルのままでいけました。

実際に動かしてみたリポジトリがこちらにありますので参考にしていただければと思います。

Github Pagesで公開されたページはこちら。