目的
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に置けばいい話だったので直下に置いた。