mkdocs

MkDocs ドキュメントサイトジェネレーター

MkDocs は、Markdown ファイルからプロジェクトのドキュメントを作成するための、高速でシンプルな静的サイトジェネレーターです。設定には単一の YAML ファイル（mkdocs.yml）を使用します。

クイックスタート

インストール

# Install MkDocs
pip install mkdocs

# Verify installation
mkdocs --version

新しいプロジェクトの作成

# Create project structure
mkdocs new my-project
cd my-project

# Start development server
mkdocs serve

作成されるプロジェクト構成：

my-project/
├── mkdocs.yml      # Configuration file
└── docs/
    └── index.md    # Homepage

最小限の設定

# mkdocs.yml
site_name: My Project
site_url: https://example.com/
nav:
  - Home: index.md
  - About: about.md

基本コマンド

コマンド	目的
mkdocs new PROJECT	新しいプロジェクトを作成します
mkdocs serve	開発サーバーを起動します（localhost:8000）
mkdocs build	静的サイトを site/ にビルドします
mkdocs gh-deploy	GitHub Pages にデプロイします
mkdocs get-deps	必要なパッケージを表示します

よく使うオプション：

• -f, --config-file FILE - カスタム設定ファイルを使用します
• -s, --strict - 警告がある場合に失敗します
• -d, --site-dir DIR - カスタム出力ディレクトリを指定します
• --dirty - 変更されたファイルのみを再ビルドします
• --clean - ビルド前に出力をクリーンアップします

プロジェクト構成

project/
├── mkdocs.yml              # Configuration (required)
├── docs/
│   ├── index.md            # Homepage
│   ├── about.md            # Additional pages
│   ├── user-guide/
│   │   ├── index.md        # Section homepage
│   │   ├── getting-started.md
│   │   └── configuration.md
│   ├── img/                # Images
│   │   └── logo.png
│   └── css/                # Custom CSS
│       └── extra.css
└── custom_theme/           # Theme customizations (optional)
    └── main.html

ナビゲーションの設定

# Automatic navigation (alphabetically sorted)
# Omit nav key to auto-generate

# Explicit navigation with sections
nav:
  - Home: index.md
  - User Guide:
      - Getting Started: user-guide/getting-started.md
      - Configuration: user-guide/configuration.md
  - API Reference: api/
  - External Link: https://example.com/

ドキュメントの作成

内部リンク

# Link to another page

[See Configuration](configuration.md)

# Link to page in another directory

[Installation](../getting-started/installation.md)

# Link to section anchor

[See Options](configuration.md#options)

ページのメタデータ

---
title: Custom Page Title
description: Page description for SEO
authors:
  - John Doe
date: 2024-01-01
---
# Page Content Here

コードブロック

```python
def hello():
    print("Hello, World!")
```

テーブル

| Header 1 | Header 2 |
| -------- | -------- |
| Cell 1   | Cell 2   |

テーマの設定

組み込みテーマ

# Default MkDocs theme
theme:
  name: mkdocs
  color_mode: auto           # light, dark, auto
  user_color_mode_toggle: true
  nav_style: primary         # primary, dark, light
  highlightjs: true
  navigation_depth: 2
  locale: en

# ReadTheDocs theme
theme:
  name: readthedocs
  prev_next_buttons_location: bottom
  navigation_depth: 4
  collapse_navigation: true

Material for MkDocs（人気のサードパーティ製）

pip install mkdocs-material

theme:
  name: material
  palette:
    primary: indigo
    accent: indigo
  features:
    - navigation.tabs
    - navigation.sections
    - search.suggest

カスタム CSS／JavaScript

extra_css:
  - css/extra.css

extra_javascript:
  - js/extra.js
  - path: js/analytics.mjs
    type: module

プラグイン

plugins:
  - search:
      lang: en
      min_search_length: 3
  - tags
  - blog

人気のプラグイン：

• search - 全文検索（組み込み、デフォルトで有効）
• blog - ブログ機能（Material テーマ）
• tags - コンテンツの分類
• social - ソーシャルメディアカード

注： plugins を定義すると、デフォルト設定が無効になります。- search を明示的に追加してください。

Markdown 拡張機能

markdown_extensions:
  - toc:
      permalink: true
      separator: "-"
  - tables
  - fenced_code
  - admonition
  - pymdownx.highlight
  - pymdownx.superfences

デプロイ

GitHub Pages

# Deploy to gh-pages branch
mkdocs gh-deploy

# With options
mkdocs gh-deploy --force --message "Deploy docs"

任意のホスト向けにビルド

# Build static files
mkdocs build

# Files output to site/ directory
# Upload to any static host

カスタムドメイン

docs/CNAME ファイルを作成します：

docs.example.com

よくあるワークフロー

新しいドキュメントプロジェクト

1. プロジェクトを作成します：mkdocs new my-docs
2. mkdocs.yml を編集して、site_name と nav を設定します
3. Markdown ファイルを docs/ に追加します
4. プレビューします：mkdocs serve
5. ビルドします：mkdocs build
6. デプロイします：mkdocs gh-deploy

ビルドのクイックプレビュー

Bash(mkdocs build --dry-run)

問題がなければ、Bash(mkdocs serve -v) で開発プレビューを行います。

新しいセクションの追加

1. ディレクトリを作成します：docs/new-section/
2. index.md とコンテンツファイルを追加します
3. mkdocs.yml の nav を更新します
4. プレビューしてリンクを確認します

テーマのカスタマイズ

1. theme.custom_dir: custom_theme/ を設定します
2. テーマの構成に合わせてオーバーライドファイルを作成します
3. テンプレートブロックを使用して、ベーステンプレートを拡張します

安全なプレビューワークフロー

1. MkDocs を確認します：Bash(which mkdocs || echo "Install: pip install mkdocs")
2. ドライランでビルドします：Bash(mkdocs build --dry-run)
3. 問題を一覧表示します：Grep -r "ERROR" site/

詳細なリファレンス

• 設定オプション： references/configuration.md を参照してください
• テーマのカスタマイズ： references/themes.md を参照してください
• プラグインの開発： references/plugins.md を参照してください
• デプロイ戦略： references/deployment.md を参照してください
• ベストプラクティス： references/best-practices.md を参照してください

---

注意点

• mkdocs serve は docs/ と mkdocs.yml を監視しますが、include_dir 経由で含めたファイルやテーマのオーバーライドは監視しません — custom_theme/main.html を編集しても再読み込みされません。サーバーを再起動してください。
• mkdocs.yml で plugins: を定義すると、デフォルトの検索プラグインが無効になります — ページがインデックスされなくなり、検索ボックスに何も表示されません。プラグインを列挙する際は、必ず - search を含めてください。
• mkdocs gh-deploy は gh-pages に強制プッシュします — 手動での編集や、そこにデプロイされた別のブランチは、警告なくすべて消去されます。履歴をクリーンにするには --no-history を使用してください。ただし、gh-pages を手動で編集しないでください。
• use_directory_urls: true（デフォルト）ではリンクの動作が変わります： page.md は page.html ではなく page/ になります。ローカルではファイルへのリンクとして機能していた生の Markdown 内の相対リンクは、デプロイ後のサイトでは機能しなくなります。
• strict: true は、認識されない設定キーを含む警告があると失敗します — デフォルトテーマを使用する設定に Material テーマ専用のオプションを追加すると、警告が出るだけでなくビルドが失敗します。strict を有効にする前に、テーマとの互換性を確認してください。
• Material テーマの navigation.instant 機能は、ページ読み込み時に実行されるサードパーティ製 JavaScript を妨げます — アナリティクス、Mermaid、MathJax では、DOMContentLoaded ではなく、document$.subscribe() フックを明示的に使用する必要があります。
• mkdocs build --dirty は変更されていないファイルをスキップしますが、ナビゲーションやテーマ設定の変更は検出しません — ページが古いナビゲーションでレンダリングされます。迷った場合は --clean（デフォルト）を使用するか、site/ を削除してください。