概要
MkDocsは、Markdown形式で書かれたドキュメントから、静的なWebサイトを生成するためのジェネレーター（生成ツール）です。近年は生成AI絡みでMarkdown自体の需要も高まっていることもあり、手を出して見ました。
対象
- Markdownでドキュメントを作成しており、Web公開を検討している方
- ドキュメントを手軽に、モダンなデザインで作成したい方
MkDocs とは
MkDocsは、Pythonで実装された静的サイトジェネレーター（Static Site Generator: SSG）の一つです。ドキュメントをMarkdownファイルとして用意し、簡単なコマンドを実行するだけで、ナビゲーション付きの整ったWebサイトとして出力できます。特別なデータベースやサーバーサイドの知識が不要で、GitHub Pagesなどの静的ホスティングサービスと非常に相性が良いです。
導入手順
Pythonとpip（Pythonのパッケージ管理システム）がインストールされている環境を前提とします。
1. インストール
pipコマンドを使用して、MkDocs をインストールします。
pip install mkdocs
2. プロジェクトの作成と初期ファイル
以下のコマンドで、新しいMkDocsプロジェクトを初期化します。
mkdocs new my-docs
cd my-docs
この操作により、プロジェクトディレクトリ（my-docs）内に以下の2つの重要なファイル/ディレクトリが作成されます。
-
mkdocs.yml: サイト全体の設定ファイルです。サイト名、ナビゲーション構造、テーマなどを定義します。 -
docs/: Markdown形式のドキュメントファイルを格納するディレクトリです。
3. サイトのプレビューとビルド
開発中は、ローカル環境でサイトの見た目を確認しながら作業を進めることができます。
プレビュー（開発サーバー起動）
以下のコマンドを実行すると、開発サーバーが起動し、Webブラウザでドキュメントをリアルタイムで確認できます。ファイルの変更は自動で反映（ホットリロード）されます。
mkdocs serve
# 起動後、ブラウザで http://127.0.0.1:8000 にアクセス
依存パッケージのバージョンによって、ホットリロードが効かないことがあります。
私の場合は click==8.2.1 を指定することで解決しました。
# pip でインストールするには
pip install click==8.2.1
サイトのビルド（静的ファイル生成）
ドキュメントが完成し、公開準備が整ったら、以下のコマンドで静的なWebサイトを構成するファイルを生成します。
mkdocs build
生成された静的ファイル群は、プロジェクトルートの**site/**ディレクトリに出力されます。このsite/ディレクトリの内容を、GitHub Pagesなどの静的ホスティングサービスにアップロードすることで公開できます。
MkDocs の基本的な設定
MkDocsを動作させるための設定は、プロジェクトルートにあるmkdocs.ymlというファイルに記述します。
mkdocs.yml の基本設定
サイトのタイトル、ナビゲーションの構造、適用するテーマなどを設定します。初期状態のファイルに、MkDocs-Materialテーマを適用する設定を加えます。
site_name: My Tech Document
nav:
- はじめに: index.md
- 導入ガイド: guide/install.md
- APIリファレンス: api.md
theme:
name: material # Materialテーマを適用
-
site_name: ドキュメントサイトのタイトルを設定します。 -
nav: 左側のナビゲーションメニューの構造を定義します。ファイルパスはdocs/ディレクトリからの相対パスで記述します。 -
theme.name: ここをmaterialに設定することで、インストールしたMkDocs-Materialテーマが適用されます。
設定可能な項目やより詳細なカスタマイズ方法については、公式ドキュメントで確認できます。
MkDocs-Material について
MkDocs-Materialは、人気のあるサードパーティテーマの一つです。高いアクセシビリティとレスポンシブデザイン、そして豊富な拡張機能が提供されています。コードブロックのシンタックスハイライトや目次表示など、技術ドキュメントに必要な機能が揃っており、単なる見た目の良さだけでなく、機能面でも優れています。
- モダンなデザイン: Google Material Designに準拠しています。
- 拡張機能: 検索機能、テーマの切り替え（ダークモードなど）、Mermaid図の埋め込みなど、多くの機能が利用可能です。
- サンプル: 実際の表示例は、以下のドキュメントで確認できます。
気になった方は以下の記事を参考に導入してみてください
まとめ
MkDocsは、Markdownという手軽な形式を活かしつつ、ドキュメントサイトを構築できる強力なツールです。本記事でご紹介した導入手順に従えば、誰でも簡単にモダンなドキュメント環境を構築できます。特にMkDocs-Materialと組み合わせることで、開発者やユーザーにとって使いやすく、見た目も美しいドキュメントを容易に提供できます。