MkDocsはmarkdownでドキュメントを作るためのフレームワークです。
簡単に設定をしたら、このようなドキュメントが書けます。
markdownで書いてビルドすると、静的htmlサイトが作成されます。
動機
WordやExcelなどでドキュメントを書くのが割りと多いと思いますが、ドキュメントの種類によって、markdownの方が向いている場合があると思います。
markdownで個人的に思う便利なところ：
- 軽い
- ただのテキストファイルなので、重たいソフトを使わなくても編集できる。
- 差分管理
- gitを使って、簡単にバージョン管理ができる。
- スタイル
- 単純なテキストをhtmlにコンパイルすると、いい感じのスタイルになる。
- プラグイン
- プラグインを追加することで、markdownの機能を増やして、もっと便利に使うこともできる。
「手順書・Wiki・API仕様書」などはmarkdownに向いていると思います。
ただ、markdownをそのまま書いてしまうと、毎回.mdファイルを更新したり、htmlに変換し直したりするのが面倒だし、忘れがちです。
また、 チームで使う時、ツールやスタイルやプラグインを合わせる必要もあります。
上記の課題を解決するために、markdownのフレームワークを調べてみたいと思いました。
以下のサイトに様々な静的サイトジェネレーターがあります。
https://jamstack.org/generators/
この中いくつか調べて、MkDocsは一番ドキュメント作成にいいと思いました。
（他にもっと良さそうなのがあれば教えてください。）
MkDocsについて
MkDocsのドキュメント： https://www.mkdocs.org/
MkDocsはpythonでツールをインストールしてから使えます。
プロジェクトを作成すると、1つのyaml設定ファイルと簡単なフォルダー構成が作成されます。
テーマやプラグインをyamlに追加して、いろいろカスタマイズできます。
コマンドを起動し、ブラウザー上で確認できます。
MkDocsのいいところ：
-
軽くて速い -
ローカルブラウザーでサイトのhot-reloadができる
-
検索機能がある
-
様々なテーマやプラグインを追加できる
-
カスタムcssとjsで細かいところまでカスタマイズできる
Material Theme
今のところ、MkDocsの気に入っているテーマは「material」っていうテーマです。
テーマ自体に様々な機能が入っています。
ドキュメント： https://squidfunk.github.io/mkdocs-material/reference/abbreviations/
以下のgifでいくつかの機能を見せます。
Mermaid
mermaid対応はまだできていないですが、開発中らしいです。
https://github.com/squidfunk/mkdocs-material/issues/2170
https://squidfunk.github.io/mkdocs-material/reference/diagrams/
mermaid対応が来たら、Flowchart・シーケンス図・ガントチャート・など...をmarkdownで書けるようになります。
例：
mermaidはいろいろできるので、ぜひ確認してください。（VSCodeのプラグインもあります。）
https://mermaid-js.github.io/mermaid-live-editor
これから
まだそんなに使ってはいないですが、役に立ちそうなので、機会があれば、実際のプロジェクトに導入して、試してみたいです。
静的サイトなので、S3で簡単にホスティングできて、IP制限も付けたら、プロジェクトの内部資料としても使えそうだと思います。