Zenn
📖

MkDocsのすゝめ

2022/10/09に公開
Docker
Markdown
MkDocs
tech

はじめに

ドキュメントに整理するとき、MkDocs を使ってみたので、その記録。下記 4 点を整理した。

  1. Python をインストールせずに Docker を使ってローカルで確認する
  2. Docker を使って HTML ファイルとしてビルドする
  3. 長くなりがちな docker コマンドを Makefile にしておく
  4. GitHub Actions で GitHub Pages にデプロイする

何番煎じかわからないので、詳しくは参考にしたサイト参照（一番下にまとめた）。

最終的なドキュメントのサイトはこんな感じになる。シンプルでいい感じ。

コードはoptimisuke/hello-mkdocsにおいた。

先に書いておくと、フォルダ構成はこんな感じ。

MkDocs

まずは、MkDocs の設定（yaml）の説明。
必要最低限で、こんな感じ。
themeにmaterialをつけてMaterial for MkDocsを使ってる。
いい感じ。
index.mdとhoge.mdがsrcフォルダの下にある。

mkdocs.yml
# contents
nav:
  - Home:
      - インデックス: index.md
      - ほげ: hoge.md

# metadata
site_name: MkDocs Test Site
docs_dir: src
use_directory_urls: false

# theme
theme:
  name: material
  language: ja

マークダウンはそれぞれこんな感じ。

src/index.md
# インデックス

最初のページ
src/hoge.md
# ホゲ

次のページ

ローカルで確認するときは、下記コマンドでサーバーが立ち上がる。
ここでは、ポートを8004にしている。
なので、ブラウザからlocalhost:8004にアクセスすると確認できる。

docker run --rm -it -v $(pwd):/docs -p 8004:8000 squidfunk/mkdocs-material

Python 使うと、いろんなものがpip installされてごちゃごちゃしちゃうので、docker 使った方が良いと思ってる。

HTML Export

次に HTML の出力。
下記コマンドで、出力できる。
siteフォルダに吐き出される。

docker run --rm -it -v $(pwd):/docs squidfunk/mkdocs-material build --clean

上記 yaml にuse_directory_urls: falseを書くことがポイント。
ローカルで、index.htmlを開いてページ遷移する場合もいい感じに開けるようになる。
これを書かないとパスがフォルダを指すので、html にアクセスできずに下記のようなページが出てくる。

Docker x Makefile

docker コマンド長くなりがちなので、Makefile を作っておく。もうちょいかっこいい Makefile 書けるようになりたい。
カレントディレクトリを指定している${PWD}の部分が、コマンドで打つ時と違う。

view:
	docker run --rm -it -v ${PWD}:/docs -p 8004:8000 squidfunk/mkdocs-material
build:
	docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material build --clean

GitHub Actions

GitHub Pages にデプロイしたかったので、GitHub Actions を使って実施した。
下記公式（Publishing your site - Material for MkDocs）ドキュメント等を参考にした。

mkdocs gh-deploy --forceコマンドの中でブランチ作って push するところまでしてくれてるから、すごくシンプル。

.github.workflow/mkdocs.yml
name: deploy mkdocs
on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Check out code
        uses: actions/checkout@v2
      - name: Configure git info
        run: |
          git config --global user.name "github-actions-for-deploy"
          git config --global user.email deploy-actions@github.com
      - name: Set up python
        uses: actions/setup-python@v2
        with:
          python-version: 3.x
      - run: pip install mkdocs-material
      - run: pip install plantuml-markdown python-markdown-math mdx_truly_sane_lists mkdocs-git-revision-date-localized-plugin mkdocs-add-number-plugin
      - name: deploy
        run: mkdocs gh-deploy --force

mainに push するとgh-pagesというブランチが出来る。まじめに、git configでユーザー名を指定したから、そのユーザー名でコミットしたことになってる。

GitHub Pages を有効にするために、下記設定をするとアクセスできるようになる。

おわりに

少し環境整えたら、いい感じのドキュメント作れるようになった。とってもいい感じ。
チームには GitHub Pages で共有して、必要に応じて非エンジニアには html で共有する（pdf にもできるらしい）感じで運用できそう。
スタイルも変えられるみたいなので、もっと使っていきたい。

参考

公式

その他

GitHubで編集を提案

Discussion