Material for MkDocsで生成したサイトをGithub Pagesで公開する
MkDocsとは
MkDocksを使うとMarkdownで記載したファイルを元に静的なサイトを生成することができます。
テーマを選択
サイトを生成するにあたってテーマを利用することで様々なテイストにカスタマイズすることができます。
Read the Docs というテーマがよく利用されていますが他にも色々とあります。
サードパーティのテーマをまとめているページもありますので自分のテイストに合うものを見つけましょう。
今回は Material for MkDocs というテーマを利用することにします。
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
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で公開されたページはこちら。
Discussion