MkDocsのテンプレート

MkDocsを使ってプライベートでも仕事でもドキュメントをまとめることが増えてきました.
リアルタイム編集には向きませんが、やはり設計ドキュメントやオンボーディング資料には向いてる気がします.

そこで自分向けにMkDocsをリポジトリに導入するためのテンプレートを作って、リポジトリにコミットしておきました.

テンプレート

mkdocs-prj-templatesというリポジトリですが、このリポジトリにユースケースに応じてテンプレートをディレクトリで分けて管理しています.
現時点では、2種類のテンプレートを作成しています.

simple

simpleは、ドキュメントだけ配置するリポジトリ向けのテンプレートです.

simple
├── Dockerfile
├── docker-compose.yaml
├── docs
│   └── index.md
└── mkdocs.yml

ドキュメントだけでなくても、docker-compose.yamlやDockerfileをリポジトリルートに設置しても気にならないなら、このテンプレートでも良さそうです.

in-docs

in-docsは、既にdocker-compose.yamlやDockerfileがリポジトリにあり、リポジトリルートを散らかしたくない時のテンプレートです.

in-docs
├── bin
│   └── docs-compose
├── docs
│   ├── Dockerfile
│   ├── docker-compose.yaml
│   └── index.md
└── mkdocs.yml

構造を見ると分かるように、Dockerfileとdocker-compose.yamlがdocsディレクトリに存在しています.
この状態だとリポジトリルートでdocker-compose upをすることができないため、ラッパースクリプトとしてbin/docs-composeを用意しています.
ドキュメント関連の操作はdocs-composeを使えば良いため、各々が独自のコマンドを実行しなくて良いですし、コマンド履歴も比較的キレイになります.

mkdocs.ymlもdocsに入れられる気がしなくもないんですが、今回は諦めました.