プロジェクトのdocsフォルダの中身をmkdocsで動かしたかった #docker-compose

目的

docsフォルダにマークダウン形式のドキュメントを記述してるうちに、これmkdocsとしても動かしたいなと思うようになった。

各自でmkdocsをインストールさせたくない為、dockerで動かないかなと
調べたところ、やっている人が居たので参考にしながらメモのつもりで残しておく。

参考にしたサイト

ディレクトリのスケルトン構成

root
 ├ docker 
 |  └ mkdocs 
 |      └ Dockerfile 
 ├ docs
 |  └ index.md
 ├ develop.yml
 └ mkdocs.yml

ファイル

mkdocs.yml

ドキュメントの定義
基本的には各自の環境で好きに記述すべし

themeは好みで適当に設定すると良い

markdown_extensionsは
mermaidが使いたいので追加しているのと
リンクを別窓で表示するために{:target="_blank"}を使うのでattr_listを追加している

site_name: 'Document'
site_description: 'Document'
use_directory_urls: false

nav:
  - はじめに: index.md

theme:
  name: material
  language: 'ja'
  features:
    - navigation.tabs
    - navigation.footer

plugins:
  - search

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - attr_list
extra:
  search:
    language: 'ja'

dev_addr: '0.0.0.0:8000'

develop.yml

開発の時だけdocker-composeコマンドに-f develop.ymlをつけて呼びだす目的
healthcheckは途中でmkdocs serveが死んでも起動しなおすために入れている

version: '3'
services:
  mkdocs:
    build:
      context: .
      dockerfile: ./docker/mkdocs/Dockerfile
    image: mkdocs
    volumes:
      - ./mkdocs.yml:/mkdocs/mkdocs.yml
      - ./docs:/mkdocs/docs
    working_dir: /mkdocs
    tty: true
    command: mkdocs serve
    ports:
      - "8000:8000"
    healthcheck:
      test: "curl -f http://localhost:8000 || exit 1"
      interval: 10s
      retries: 10
      timeout: 2s
    restart: always

/docker/mkdocs/Dockerfile

参考サイトのをほぼ使用しました。

FROM python:3.10.6-bullseye

RUN adduser -q --gecos "" --disabled-login mkuser \
    && pip install mkdocs mkdocs-material fontawesome-markdown mdx_unimoji python-markdown-math pymdown-extensions \

index.md

# はじめに

## 概要

アプリケーションのドキュメントになります。

動作確認

dockerを起動

docker-compose -f develop.yml up -d

起動後にhttp://localhost:8000/を開いて下記の画面が出れば成功

最後に

最初はdocsフォルダの中にmkdocs.ymlを置いてさらにdocsフォルダを置くとか考えていた

しかし、パッと見たディレクトリが/docs/docsになって気持ち悪いなって思い
よくよく考えればmkdocs.ymlをプロジェクトのrootに置けばいい話だったので直下に置いた。