MkDocs を使って GitHub Pages に公開する¶

mkdocs-materialのサイトに沿って GitHub Pages の公開を進めた。コンテンツ自体は submodule として扱っている。

工夫したところはデプロイ用の GitHub Actions を用意したところで、最近公式から出たものを使ってみた。苦労したところは MkDocs の検索がなかなか有効にできなかったところ。

技術選定¶

基本無料で GitHub のエコシステムにのっかれるので GitHub Pages を使ってサイトを公開することにした。最近 Pages の公開がブランチ指定ではなく Actions から出来るようになったので使ってみたいというのも理由の 1 つ。

記事は Markdown でサクッと書けるように、それに対応しているサービスを探した。

探してみると Markdown で文章を書けるサービスはいろいろあるが、mkdocs-materialを使うことにした。私が普段触っている OSS のドキュメントがこれで書かれていて、どんな機能があって何ができるかイメージできたのと気になるプラグインmkdocstirngがあったから。Markdown で文章書いておけば代替のサービスはたくさんあるので移行も簡単そう。

デプロイ¶

依存関係を pip でインストールして、サイトをビルド。ビルドしたものをアーティファクトとして出力、そのアーティファクトを GitHub Pages に公開している。公開する作業が終わればアーティファクトの削除が走る。

従来の GitHub Pages で公開する際には公開用のブランチを作る必要があったが、今回のやり方ではそれが必要ない。

.github/workflows/mkdocs.yml
name: GitHub Pages

on:
  push:
    branches:
      - master
  workflow_dispatch:

concurrency:
  group: "pages"
  cancel-in-progress: true

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-22.04
    timeout-minutes: 3
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: recursive
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v2
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.10"
          cache: "pip"

      - name: Install dependencies
        run: pip install -r ./requirements.txt

      - run: mkdocs build
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          path: ./site

  # Deployment job
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v1

      - uses: geekyeggo/delete-artifact@v1
        with:
          name: github-pages

Python セットアップ時に pip のキャッシュを使おうとしているが、実はうまく使えてない。requirements.txtの中でfoo=1.0.0のようにバージョンを固定すればキャッシュが効くらしい。

検索の有効化¶

日本語の検索がうまくできずハマった。lang に en を含むことで動作するようになったが、これが意図した挙動なのかバグなのかは分かっていない。

mkdocs.yml
plugins:
  - monorepo
  - search:
      lang:
        - ja
        - en