らくがきちょう

なんとなく ～所属組織/団体とは無関係であり、個人の見解です～

HBFM (Markdown 拡張) を追加した MkDocs の Docker イメージ

Docker

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

参考