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に入れられる気がしなくもないんですが、今回は諦めました.
