MkDocs を使って GitHub Pages に公開する
MkDocs Material で Markdown の記事をサイトにし、公式が提供する Actions を使って GitHub Pages へ公開した。記事を submodule で管理する構成、デプロイのワークフロー、検索の設定でつまずいた点をまとめる。構築ではMkDocs Material の導入ドキュメントを参考にした。
技術選定
基本無料で GitHub のエコシステムにのっかれるので GitHub Pages を使ってサイトを公開することにした。Pages の公開がブランチ指定ではなく Actions から出来るようになったので使ってみたいというのも理由の 1 つ。
記事は Markdown で手軽に書きたかったので、それに対応しているサービスを探した。
探してみると、Markdown で文章を書けるサービスはいろいろある。その中でmkdocs-materialを使うことにした理由は 2 つある。1 つは、私が普段触っている OSS のドキュメントがこれで書かれていたことだ。おかげで、どんな機能があって何ができるかイメージできた。もう 1 つは、気になるプラグインmkdocstringsがあったことだ。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 のキャッシュを使おうとしているが、実はうまく使えていない。
検索の有効化
日本語の検索がうまくできずハマった。lang に en を含むことで動作するようになったが、これが意図した挙動なのかバグなのかは分かっていない。
| mkdocs.yml |
|---|
| plugins:
- monorepo
- search:
lang:
- ja
- en
|
