MkDocs + Materialで美しいドキュメントサイトを作る完全ガイド｜初心者向け

プロジェクトのドキュメント、どうやって公開していますか？ MkDocs + Material theme なら、Markdownだけで検索機能付きの美しいドキュメントサイトが作れます。

この記事では、インストールからカスタマイズ、公開方法まで、MkDocsの使い方を実践的に解説します。

MkDocsが活躍する場面

MkDocsは、以下のような用途で特に威力を発揮します：

• 個人プロジェクトのドキュメント公開 - GitHubのプロジェクトに美しいドキュメントサイトを追加
• 技術ナレッジベース・社内wiki - チームで共有する技術情報を整理
• オープンソースプロジェクトの公式ドキュメント - 多くの著名プロジェクトが採用
• 学習記録・ポートフォリオサイト - 技術的な成長過程を可視化
• Fab Academy等の学習プログラム - 週次レポートや課題提出に最適

MkDocs とは?

MkDocsは、特にソフトウェア開発ドキュメントの作成に適した、静的サイトジェネレーターです。Markdownを使用してコンテンツを書き、リアルタイムでプレビューしながらプロジェクトドキュメントのウェブサイトを構築することができます。

MkDocs 主な特徴

動作環境

この記事の手順は以下の環境で動作します：

• macOS: 10.15以降（Intel/Apple Silicon対応）
• Windows: Windows 10/11
• Linux: 主要ディストリビューション
• Python: 3.8以降
• pip: Python 3.8以降に標準同梱

注意: macOSではHomebrewを使用したインストールを推奨します。WindowsではPython公式サイトからインストーラーをダウンロードしてください。

MkDocsのインストール手順

お使いのOSに応じて、以下の手順でインストールしてください。

macOS の場合

1. Homebrewをインストール（未インストールの場合）

Macでパッケージ管理を行うため、まずHomebrewをインストールします。

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

詳細は Homebrew公式サイト を参照してください。

2. Pythonとpipをインストール

Homebrewを使ってPythonをインストールします（pipも一緒にインストールされます）。

brew install python

インストール確認：

python3 --version
python3 -m pip --version

3. MkDocsをインストール

pipを使ってMkDocsをインストールします。

python3 -m pip install mkdocs

インストール確認：

mkdocs --version

Windows の場合

1. Pythonをインストール

Python公式サイトから最新のPython 3.x インストーラーをダウンロードします。

インストール時の注意点：

• 重要: “Add Python to PATH” に必ずチェックを入れる
• “Install Now” をクリックしてインストール

2. インストール確認

コマンドプロンプトまたはPowerShellを開いて確認：

python --version
python -m pip --version

3. MkDocsをインストール

python -m pip install mkdocs

インストール確認：

mkdocs --version

Linux の場合

1. Pythonとpipをインストール

多くのLinuxディストリビューションにはPython 3がプリインストールされていますが、念のため確認します。

Ubuntu/Debian系:

sudo apt update
sudo apt install python3 python3-pip

Fedora/RHEL系:

sudo dnf install python3 python3-pip

Arch Linux:

sudo pacman -S python python-pip

2. インストール確認

python3 --version
python3 -m pip --version

3. MkDocsをインストール

python3 -m pip install --user mkdocs

注意: --userオプションを付けることで、ユーザーディレクトリにインストールされます（権限エラーを回避）。

インストール確認：

mkdocs --version

パスが通っていない場合は、以下を~/.bashrcまたは~/.zshrcに追加：

export PATH="$HOME/.local/bin:$PATH"

最初のサイトを動かしてみよう

インストールが完了したら、まずは動作確認をしてみましょう。

mkdocs new mysite      # 新しいMkDocsプロジェクト（mysiteフォルダ）を作成
cd mysite              # 作成したディレクトリへ移動
mkdocs serve           # ローカルプレビューサーバー起動（http://127.0.0.1:8000でプレビュー）

• ローカルサーバー起動後: ブラウザで http://127.0.0.1:8000 を開くと、ローカルサイトが確認できます。
• ローカルサーバーを終了する場合：ターミナルで Ctrl + C を押してください。

Material テーマのインストール

MkDocsには様々なテーマが用意されており、ドキュメントの外観を簡単にカスタマイズできます。

この記事では、最も人気のあるMaterial for MkDocsテーマを使用します。Material for MkDocsは、Google Material Designに基づいた美しいデザインと、豊富な機能を提供します。

テーマ一覧

他のテーマを探したい場合は、MkDocs Themes一覧を参照してください。

Materialテーマのインストール

pipを使って簡単にインストールできます。お使いのOSに応じて以下のコマンドを実行してください。

macOS / Linux:

python3 -m pip install mkdocs-material

Linuxで権限エラーが出る場合は--userオプションを追加：

python3 -m pip install --user mkdocs-material

Windows:

python -m pip install mkdocs-material

mkdocs.ymlの編集 (Mkdocs カスタマイズ)

MkDocsのカスタマイズは、プロジェクトルートのmkdocs.ymlファイルで行います。

基本設定

まずは最小限の設定から始めましょう。

site_name: SAMPLE SITE

site_dir: 'public'

theme:
  name: material

  features:
    - content.code.copy

  palette:
    primary: teal
    scheme: slate

# Copyright
copyright: Copyright © 20xx SAMPLE SITE

カスタマイズ後のサイト

よく使うカスタマイズ例

1. ダークモード切り替えボタンを追加

theme:
  palette:
    # ライトモード
    - media: '(prefers-color-scheme: light)'
      scheme: default
      primary: indigo
      toggle:
        icon: material/brightness-7
        name: ダークモードに切り替え
    # ダークモード
    - media: '(prefers-color-scheme: dark)'
      scheme: slate
      primary: indigo
      toggle:
        icon: material/brightness-4
        name: ライトモードに切り替え

2. カラーパレットの設定

Materialテーマでは、豊富なカラーパレットが用意されています。

利用可能なカラー一覧:

red, pink, purple, deep purple, indigo, blue, light blue, cyan, teal, green, light green,
lime, yellow, amber, orange, deep orange, brown, grey, blue grey, black, white

設定例:

theme:
  palette:
    primary: teal # ヘッダーやリンクの色
    accent: indigo # ボタンやハイライトの色

プロジェクトのブランドカラーに合わせて自由に変更できます。

3. ナビゲーションの設定

nav:
  - ホーム: index.md
  - はじめに: getting-started.md
  - チュートリアル:
      - 基礎編: tutorial/basics.md
      - 応用編: tutorial/advanced.md
  - リファレンス: reference.md

これらの設定により、より使いやすく魅力的なドキュメントサイトが構築できます。

MkDocsの基本コマンド

mkdocs new mysite     # 新規プロジェクト作成
cd mysite             # ディレクトリ移動
mkdocs serve          # ローカルプレビュー（http://127.0.0.1:8000）
mkdocs build          # HTMLをビルド

注: 実行中のサーバーを停止する場合は Ctrl + C

テキストの編集

文を編集する場合は、ファイル（拡張子：*.md）を追加して編集します。

＜例＞

テキスト編集後のサイト

GitHub Pagesで公開する（3分で完了）

作成したドキュメントサイトは、GitHub Pagesで無料で公開できます。

1. GitHubリポジトリを作成

プロジェクトをGitHubにpushします。

git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/ユーザー名/リポジトリ名.git
git push -u origin main

2. GitHub Pagesにデプロイ

MkDocsには専用のデプロイコマンドが用意されています。

mkdocs gh-deploy

このコマンド一つで、gh-pagesブランチにビルド済みのサイトがpushされ、自動的に公開されます。

3. 公開URLを確認

数分後、以下のURLでサイトが公開されます：

https://ユーザー名.github.io/リポジトリ名/

GitHub Actionsを使えば、mainブランチへのpush時に自動デプロイすることも可能です。

よくあるエラー

GitHub Pagesへのデプロイ時によくあるエラーと解決方法：

• remote origin not found: git remote add origin を実行してリモートリポジトリを追加してください
• Permission denied (publickey): SSHキーをGitHubに登録する必要があります。GitHub SSH設定ガイドを参照してください

参考リンク

• fabcloud

  • tutorials for MkDocs

• MkDocs Configuration

• Material for MkDocs / code-blocks