コンテンツにスキップ

MkDocs

MkDocsは、Markdownドキュメントから静的サイトを生成するツールです。

動かす

Material for MkDocs

マテリアルデザインのテーマが適用されたMkDocs。Dockerで動作可能。

Material for MkDocs + Plantuml

今回はPlantumlも使いたいので下記のリポジトリを使用する。

Github - mikaelhg/mkdocs-material-plantuml

ビルド

プロジェクトフォルダ上で実行。

$ docker run --rm -it -v ${PWD}:/docs ghcr.io/mikaelhg/mkdocs-material-plantuml:latest

開発用サーバー

ファイルの変更を検知してリロードしてくれる。

$ docker run --rm -it -p 8000:8000 -v ${PWD}:/docs ghcr.io/mikaelhg/mkdocs-material-plantuml:latest serve --dev-addr=0.0.0.0:8000

デプロイ (Github Actions)

Pushするとサイトが生成されるように設定する。

流れとしては次の通り(Github Actionsをよく知らないので間違った理解の可能性あり)。

  1. on: push: - mainでpushを検知。
  2. actions/checkout@v2
  3. docker://ghcr.io/mikaelhg/mkdocs-material-plantuml:latestで静的サイトを生成(コンテナのEntrypointがbuildになっている、volumeにどうやって紐づけているかは不明)
  4. peaceiris/actions-gh-pages@v3で生成されたサイトをGithub Pagesにデプロイ。
on:
  push:
    branches:
      - main
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: mkdocs build
        uses: docker://ghcr.io/mikaelhg/mkdocs-material-plantuml:latest
      - uses: peaceiris/actions-gh-pages@v3
        with:
          personal_token: ${{ secrets.PERSONAL_TOKEN }}
          external_repository: kokshi/publish-doc
          publish_dir: ./site

参考