MkDocsでマニュアルを作る #1 インストールから最初のドキュメントまで

ドキュメントを本格的に作り始めると、ほぼ例外なく同じ問題に出会います。README1枚では手に負えないドキュメントをどこに積み上げるか、という問題です。Notionは外部公開やバージョン管理が面倒で、ブログツールで作ると記事が時系列に並ぶだけでリファレンスとして使いづらいものです。そこで多くのチームが、ドキュメントをコードのように扱う方式、つまりDocs as Codeへ移っていきます。マークダウンで書き、Gitで管理し、静的サイトとしてデプロイする方式です。

このシリーズは、その最初の一歩である静的サイトジェネレーターでドキュメントサイトを建てる方法を扱います。ツールはMkDocsです。Pythonで作られていて設定がシンプルなので、特にすでにPythonを使っているチームであれば、もっとも参入障壁の低い選択肢です。テーマはドキュメントに特化したMaterial for MkDocsを使います。

今回のシリーズはMkDocsでマニュアルを作る全6回です。

• #1 インストールから最初のドキュメントまで ← この記事
• #2 navと検索 — ドキュメントの情報構造を整える
• #3 コンテンツ作成 — コードブロック、Mermaid、admonition
• #4 Cloudflare Pagesでデプロイしてドメインをつなぐ
• #5 多言語とバージョン管理
• #6 メンテナンス — 検索、アクセシビリティ、ドキュメント文化

この記事では、MkDocsが何を準備物として要求するのか、そして新しいサイトを作ってMaterialテーマを適用し、ローカルで最初のドキュメントを表示するところまでを、実際に動かしながら締めくくります。

準備物 — Pythonひとつあれば十分です #

MkDocsはPythonパッケージです。そのため準備物もシンプルです。Python 3とpipさえあれば大丈夫です。HugoのようにGoの環境まで用意する必要はなく、すでにPythonが入った環境ならすぐに始められます。

インストール #

インストールはプロジェクトごとの仮想環境(venv)の中で行うことをおすすめします。システムのPythonを汚さずに、ドキュメントツールのバージョンをプロジェクトごとに別々に管理できるからです。

# プロジェクトフォルダで仮想環境を作成して有効化
python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate

# Materialテーマをインストール(mkdocs本体も一緒に入ります)
pip install mkdocs-material

mkdocs-materialをインストールすると、MkDocs本体が依存関係として一緒にインストールされます。インストール後にバージョンを確認します。

mkdocs --version

新しいサイトを作る #

空のドキュメントサイトの骨組みを作ります。現在のフォルダにそのまま生成するには、ドット(.)を引数として渡します。

mkdocs new .

このコマンドは2つを作ります。設定ファイルmkdocs.ymlと、最初のドキュメントが入ったdocs/index.mdです。ドキュメントはすべてdocsフォルダの中に積み上がります。

Materialテーマの適用 #

生成されたmkdocs.ymlを開いて、テーマをMaterialに指定します。デフォルト値は素っ気ない組み込みテーマなので、この1行を変えるだけで、検索・ダークモード・レスポンシブが揃ったドキュメントサイトになります。

site_name: 製品マニュアル
theme:
  name: material

最初のドキュメントを表示する #

それではローカルサーバーを起動します。ファイルを直すと画面が自動でリロードされます。

mkdocs serve

ブラウザでhttp://127.0.0.1:8000を開くと、Materialのレイアウトに最初のドキュメントが現れます。ドキュメントをもう1編追加してみます。docsフォルダにファイルを作ればよいだけです。

# docs/getting-started.md を作って本文を書き込みます

フォルダ構造を理解する #

ここまでに作られた構造のうち、今すぐ知っておくべきはdocsという一か所と設定ファイルです。

my-docs/
├─ mkdocs.yml         # サイト設定
├─ docs/              # ドキュメント本文(ここだけ埋めればよいです)
│  ├─ index.md        # 最初の画面
│  └─ getting-started.md
└─ site/              # mkdocs build の成果物(デプロイ用)

ドキュメントを増やす作業は、結局docsの下にマークダウンファイルを足す作業です。ただし、Hugoがフォルダ構造をそのままサイドバーにしていたのとは違い、MkDocsはサイドバー(nav)をmkdocs.ymlに直接書いて、順序とまとまりを決めます。その方法は次回で本格的に扱います。

まとめ #

この記事では、Pythonの仮想環境にMkDocs Materialをインストールし、新しいサイトにテーマを適用してローカルで最初のドキュメントを表示するところまで終えました。設定ファイル1行で検索まで揃ったドキュメントサイトが始まる点が、MkDocsの最大の長所です。

次回はnavと検索を扱います。ドキュメントが数十編に増えても読者が迷わないように、mkdocs.ymlで情報構造を設計する段階です。