久々に使い勝手の良さに感動した

ドキュメンテーションツールといえば Sphinx が定番だったし過去私もよく使用していたのだが Sphinx が標準でサポートしているマークアップ言語である reStructuredText がお世辞にも書きやすいとは言えず常に記法を調べたり別の箇所からコピペするなどして頑張って書いていた記憶がある。最近では技術系に関わらず文書を起こす場合は Markdown がデファクトの地位を確立していると思う。 Sphinx でも設定すれば Markdown を使えるようだがこれも使い勝手がいいとはいえない。設定が簡単で Markdown を書くことに集中できるようなツールを探していたのだが、今回見つけた MkDocs がとても素晴らしかったので自分用メモを兼ねてここに書き記しておく。

Markdown なのに最初から表組みの拡張が入っている (しかも書きやすい)
mkdocs serve でローカルサーバが起動するが Markdown ドキュメントを編集すると即時反映される (ビルド不要)
Sphinx の admonition だったり footnotes (注釈) が設定 1 行付け足すだけで簡単に使用できるようになるし他の機能も必要に応じて 1 行書くだけで即追加可能

導入・設定

導入に関してはカンタンにドキュメントが作れるmkdocsをはじめてみようがとても分かりやすかった。基本は Python をインストールして pip からすべて導入できるので楽だ。細かい設定に関しては MkDocsによるドキュメント作成が詳しい。

その他の設定は MkDocs 公式 (英語) を確認すればよい。また使用するテーマに関してだが readthedocs か material のどちらかがいいということだが私は material にした。 CSS をいじらずに配色 (マテリアルデザインにおけるテーマ色とアクセント色) が簡単に変更できるし、日本語対応がされている。後何故か readthedocs の方だとコードハイライト時にうまく表示されなかった。

私が導入した設定

site_name: 'サイトネーム'
site_description: 'サイト説明'
site_author: '所有者名'
site_url: 'サイト URL'
copyright: '著作表記'

theme:
  name: 'material'
  language: 'ja'
  palette:
    primary: 'light blue'
    accent: 'pink'
  font:
    text: 'UD デジタル 教科書体 NK-R'
    code: 'Consolas'
    
extra:
  search:
    language: 'jp'
    
markdown_extensions:
  - admonition
  - codehilite
  - footnotes
  - pymdownx.inlinehilite
  - pymdownx.tasklist:
      custom_checkbox: true

Material for MkDocs

Material for MkDocs 公式 (英語) にすべて網羅されているので設定はここを見れば良い。言語ロケールの選択をすると全体的に日本語表記になる (検索も日本語対応されている) し、テーマ色やフォント (コードハイライトと別々に定義できる) の設定も可能だ。

Extensions

以下を導入した:

Admonition (Sphinx のような警告文)
CodeHilite (コードハイライト)
Footnotes (文末注釈)
pymdownx.inlinehilite (インラインコードのハイライト)
pymdownx.tasklist (チェックリスト)