MkDocs を使うと Markdown を使ったドキュメント構築を手軽に行えます。 基本的なコンセプトは Sphinx と同じですが、Sphinx は reST(reStructuredText)メインなのに対して、MkDocs は Markdown メインというところが大きな差だと思います。 どちらも優れたソフトウェアだと思いますが、私の場合は Markdown の方が慣れているので MkDocs の方が手軽に感じます。
更に MkDocs に HEARTBEATS Flavored Markdown extension (以下、HBFM)をインストールすると「フォントに色をつける」等の機能拡張を行うことが出来ます。 MkDocs も HBFM も pip
で簡単にインストール可能ですが、今回は Alpine に両方をインストールした Docker イメージを作成し、これを利用します。
プロジェクトを新規作成する
以下で my-project
というプロジェクトが新規作成されます。
docker run -it --rm -v `pwd`:/docs sig9/docker-mkdocs new my-project
HBFM を有効可する
プロジェクトディレクトリ直下の mkdocs.yml
は、デフォルトで以下のようになっています。
site_name: My Docs
これに以下を追記し、HBFM を有効化します。
markdown_extensions: - hbfm.inline_coloring - hbfm.inline_list - toc: slugify: !!python/name:hbfm.toc.slugify - hbfm.number_headers - hbfm.quote_uri_hash
MkDocs の組み込み Web サーバを起動する
MkDocs の組み込み Web サーバを利用すると、ドキュメントが変更される度にリアルタイムでブラウザでのレビューが可能です。 組み込み Web サーバは以下のように起動出来ます。
docker run -it --rm -v `pwd`:/docs -p 8000:8000 sig9/docker-mkdocs serve -a 0.0.0.0:8000
静的ファイルを出力する
公開用に静的ファイルを出力するには以下を実行します。
docker run -it --rm -v `pwd`:/docs sig9/docker-mkdocs build
mkdocs.yml
mkdocs.yml
のサンプルは以下の通りです。
# Overview site_name: My Docs # Documentation and theme docs_dir: 'docs' theme: 'material' # Options extra: palette: primary: 'Light Blue' accent: 'Orange' font: text: 'Roboto' code: 'Roboto Mono' i18n: prev: 'Previous' next: 'Next' # Extensions markdown_extensions: - admonition - codehilite(css_class=code) - hbfm.inline_coloring - hbfm.inline_list - toc: permalink: '#' slugify: !!python/name:hbfm.toc.slugify - hbfm.number_headers - hbfm.quote_uri_hash