MkDocs
Python製のドキュメント特化SSG。18k超のGitHubスターを持ち、Markdownベースのドキュメント作成に特化。
トレンド・動向
API仕様書や技術ドキュメント作成で人気。Material for MkDocsテーマにより美しいドキュメントを簡単作成。
# 静的サイトジェネレータ
MkDocs
## 概要
MkDocsは2014年からPython製のドキュメント特化型SSGとして開発され、18k超のGitHubスターを誇るMarkdownベースの技術ドキュメント作成に特化したツールです。シンプルな設定とクリーンなMarkdown記法により、API仕様書・技術ドキュメント・プロジェクトマニュアルの作成が容易。Material for MkDocsテーマによる美しい見た目と検索機能、バージョニング対応により、オープンソースプロジェクトから企業の技術ドキュメントまで幅広く採用されています。
## 詳細
MkDocs 2025年版は技術ドキュメント作成におけるデファクトスタンダードとして確立し、Pythonエコシステムとの親和性により開発者フレンドリーな環境を提供します。YAML設定ファイルによるシンプルな構成管理、Jinja2テンプレートエンジンによる柔軟なカスタマイズ、豊富なプラグインエコシステムによる機能拡張が特徴。特にMaterial for MkDocsテーマは、Googleのマテリアルデザインを採用した美しいUIと高度な検索機能、ダークモード対応、レスポンシブデザインにより、モダンな技術ドキュメントサイトを簡単に構築できます。
### 主な特徴
- **ドキュメント特化設計**: API仕様書・技術マニュアル・チュートリアルに最適化
- **Material for MkDocsテーマ**: Googleマテリアルデザインベースの美しいUI
- **強力な検索機能**: インデックス化された高速検索とハイライト表示
- **バージョニング対応**: 複数バージョンのドキュメント管理
- **プラグインエコシステム**: Pythonベースの豊富な機能拡張
- **ライブリロード**: リアルタイムプレビューによる効率的な編集
- **多言語対応**: i18nプラグインによる国際化サポート
## メリット・デメリット
### メリット
- シンプルなMarkdown記法とYAML設定による直感的なドキュメント作成
- Material for MkDocsテーマによるプロフェッショナルで美しい外観
- 高速な検索機能とユーザビリティに優れたナビゲーション
- Pythonエコシステムとの統合による開発ワークフローの効率化
- バージョニング・多言語対応による大規模プロジェクト対応
- GitHub ActionsやCI/CDとの連携による自動デプロイメント
- 豊富なプラグインによる機能拡張とカスタマイズ性
### デメリット
- Python環境が必要でRubyやNode.js環境との互換性制限
- ブログ機能は基本的になく、技術ドキュメント以外の用途には不向き
- 大規模サイトでのビルド速度がHugoやZolaに比べて劣る
- テーマの選択肢がJekyllやHugoに比べて限定的
- 複雑なレイアウトカスタマイズにPython/Jinja2の知識が必要
- ドキュメント特化のため汎用Webサイト構築には機能不足
## 参考ページ
- [MkDocs 公式サイト](https://www.mkdocs.org/)
- [MkDocs GitHub リポジトリ](https://github.com/mkdocs/mkdocs)
- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)
## 書き方の例
### インストールとプロジェクト作成
```bash
# Pythonとpipの確認
python3 --version
pip3 --version
# MkDocsのインストール
pip install mkdocs
# Material for MkDocsテーマのインストール（推奨）
pip install mkdocs-material
# 新しいプロジェクトの作成
mkdocs new my-project
cd my-project
# プロジェクト構造の確認
ls -la
# mkdocs.yml (設定ファイル)
# docs/ (ドキュメントディレクトリ)
# index.md (ホームページ)
# 開発サーバーの起動
mkdocs serve
# => http://127.0.0.1:8000 でアクセス可能
# 特定のポート・ホストでの起動
mkdocs serve --dev-addr=127.0.0.1:8080
# デバッグモードでの起動
mkdocs serve --verbose
```
### 基本設定ファイルの構成
```yaml
# mkdocs.yml - 基本設定
site_name: My Technical Documentation
site_description: Comprehensive technical documentation site
site_author: Your Name
site_url: https://your-domain.com
# リポジトリ設定
repo_name: username/my-project
repo_url: https://github.com/username/my-project
edit_uri: edit/main/docs/
# テーマ設定（Material for MkDocs使用）
theme:
name: material
language: ja
palette:
# ライトモード
- scheme: default
primary: indigo
accent: indigo
toggle:
icon: material/brightness-7
name: Switch to dark mode
# ダークモード
- scheme: slate
primary: indigo
accent: indigo
toggle:
icon: material/brightness-4
name: Switch to light mode
features:
- navigation.instant
- navigation.tracking
- navigation.tabs
- navigation.sections
- navigation.expand
- navigation.top
- search.suggest
- search.highlight
- search.share
- content.code.annotate
- content.code.copy
icon:
repo: fontawesome/brands/github
# ナビゲーション構造
nav:
- ホーム: index.md
- 導入:
- インストール: getting-started/installation.md
- クイックスタート: getting-started/quickstart.md
- APIリファレンス:
- 認証: api/authentication.md
- エンドポイント: api/endpoints.md
- ガイド:
- ベストプラクティス: guides/best-practices.md
- トラブルシューティング: guides/troubleshooting.md
- リリースノート: changelog.md
# Markdown拡張機能
markdown_extensions:
- admonition
- pymdownx.details
- pymdownx.superfences
- pymdownx.highlight:
anchor_linenums: true
- pymdownx.inlinehilite
- pymdownx.snippets
- pymdownx.tabbed:
alternate_style: true
- pymdownx.tasklist:
custom_checkbox: true
- attr_list
- md_in_html
- toc:
permalink: true
# プラグイン設定
plugins:
- search:
lang: ja
- git-revision-date-localized:
type: date
# 追加CSS・JavaScript
extra_css:
- stylesheets/extra.css
extra_javascript:
- javascripts/extra.js
# カスタム変数
extra:
version: 1.0.0
social:
- icon: fontawesome/brands/github
link: https://github.com/username
- icon: fontawesome/brands/twitter
link: https://twitter.com/username
```
### ドキュメントコンテンツの作成
```markdown
<!-- docs/index.md -->
# プロジェクト概要
このサイトは技術ドキュメントの包括的なガイドです。
## 特徴
!!! info "重要な情報"
このプロジェクトはPython 3.8以上が必要です。
### 主要機能
- [x] 高速なAPI処理
- [x] 安全な認証システム
- [ ] 多言語対応（開発中）
## インストール
```bash
pip install my-project
```
### 基本的な使用方法
```python
import my_project
# クライアントの初期化
client = my_project.Client(api_key="your-api-key")
# データの取得
data = client.get_data()
print(data)
```
## コード例
=== "Python"
```python
def hello_world():
return "Hello, World!"
print(hello_world())
```
=== "JavaScript"
```javascript
function helloWorld() {
return "Hello, World!";
}
console.log(helloWorld());
```
=== "Bash"
```bash
#!/bin/bash
echo "Hello, World!"
```
## 次のステップ
1. [インストールガイド](getting-started/installation.md)を確認
2. [クイックスタート](getting-started/quickstart.md)でプロジェクトを開始
3. [APIリファレンス](api/authentication.md)で詳細を学習
---
<!-- docs/api/authentication.md -->
# 認証
## 概要
APIアクセスにはAPIキーによる認証が必要です。
!!! warning "セキュリティ注意"
APIキーは秘密情報として適切に管理してください。
## APIキーの取得
1. [開発者ポータル](https://dev.example.com)にアクセス
2. アカウントを作成またはログイン
3. 新しいAPIキーを生成
## 認証方法
### ヘッダー認証
```http
GET /api/v1/data HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```
### クエリパラメータ認証
```http
GET /api/v1/data?api_key=YOUR_API_KEY HTTP/1.1
Host: api.example.com
```
## エラーハンドリング
| ステータスコード | 説明 | 解決方法 |
|-----------------|------|----------|
| 401 | 認証エラー | APIキーを確認 |
| 403 | 権限不足 | アクセス権限を確認 |
| 429 | レート制限 | しばらく待ってから再試行 |
!!! example "認証例"
```python
import requests
headers = {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
}
response = requests.get(
'https://api.example.com/v1/data',
headers=headers
)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
```
```
### テーマカスタマイズとスタイリング
```yaml
# mkdocs.yml - 高度なテーマ設定
theme:
name: material
language: ja
# カスタムディレクトリ（オーバーライド用）
custom_dir: overrides/
# カラーパレット設定
palette:
- media: "(prefers-color-scheme: light)"
scheme: default
primary: blue
accent: blue
toggle:
icon: material/brightness-7
name: Switch to dark mode
- media: "(prefers-color-scheme: dark)"
scheme: slate
primary: blue
accent: blue
toggle:
icon: material/brightness-4
name: Switch to light mode
# フォント設定
font:
text: Roboto
code: Roboto Mono
# ファビコン
favicon: assets/favicon.png
# ロゴ
logo: assets/logo.png
# 機能設定
features:
- announce.dismiss
- content.action.edit
- content.action.view
- content.code.annotate
- content.code.copy
- content.code.select
- content.tooltips
- navigation.footer
- navigation.indexes
- navigation.instant
- navigation.instant.prefetch
- navigation.instant.progress
- navigation.path
- navigation.prune
- navigation.sections
- navigation.tabs
- navigation.tabs.sticky
- navigation.top
- navigation.tracking
- search.highlight
- search.share
- search.suggest
- toc.follow
```
```css
/* docs/stylesheets/extra.css */
:root {
--md-primary-fg-color: #1976d2;
--md-primary-fg-color--light: #42a5f5;
--md-primary-fg-color--dark: #1565c0;
--md-accent-fg-color: #ff4081;
}
/* カスタムアドモニション */
.md-typeset .admonition.custom,
.md-typeset details.custom {
border-color: #448aff;
}
.md-typeset .custom > .admonition-title,
.md-typeset .custom > summary {
background-color: #448aff1a;
border-color: #448aff;
}
.md-typeset .custom > .admonition-title::before,
.md-typeset .custom > summary::before {
background-color: #448aff;
mask-image: var(--md-admonition-icon--note);
}
/* コードブロックのカスタマイズ */
.md-typeset .highlight pre {
border-radius: 0.2rem;
}
/* ナビゲーションの調整 */
.md-nav__title {
font-weight: 700;
}
/* フッターのカスタマイズ */
.md-footer {
background-color: var(--md-footer-bg-color);
}
/* レスポンシブ調整 */
@media screen and (max-width: 76.1875em) {
.md-nav--primary .md-nav__title {
background-color: var(--md-primary-fg-color);
}
}
```
### プラグイン設定と機能拡張
```yaml
# mkdocs.yml - プラグイン設定
plugins:
# 検索機能
- search:
lang:
- ja
- en
separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'
# Git情報プラグイン
- git-revision-date-localized:
enable_creation_date: true
type: timeago
timezone: Asia/Tokyo
locale: ja
# Git著者情報
- git-authors:
show_contribution: true
show_line_count: true
count_empty_lines: false
# Mermaidダイアグラム
- mermaid2:
arguments:
theme: neutral
# タグ機能
- tags:
tags_file: tags.md
# マクロ機能
- macros:
include_dir: docs/includes
# PDF出力
- pdf-export:
verbose: true
media_type: print
enabled_if_env: ENABLE_PDF_EXPORT
# API文書生成
- mkdocstrings:
handlers:
python:
options:
docstring_style: google
show_source: true
# 多言語対応
- i18n:
default_language: ja
languages:
ja:
name: 日本語
build: true
en:
name: English
build: true
nav_translations:
en:
ホーム: Home
導入: Getting Started
APIリファレンス: API Reference
ガイド: Guides
リリースノート: Release Notes
# Markdown拡張機能詳細設定
markdown_extensions:
# メタデータ
- meta
# 目次
- toc:
permalink: true
baselevel: 1
separator: "_"
# アドモニション
- admonition
- pymdownx.details
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
# コードハイライト
- pymdownx.highlight:
anchor_linenums: true
line_spans: __span
pygments_lang_class: true
- pymdownx.inlinehilite
- pymdownx.snippets:
check_paths: true
# タブ
- pymdownx.tabbed:
alternate_style: true
# タスクリスト
- pymdownx.tasklist:
custom_checkbox: true
# 数式
- pymdownx.arithmatex:
generic: true
# 絵文字
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg
# 略語
- abbr
# 定義リスト
- def_list
# HTML属性
- attr_list
- md_in_html
# 脚注
- footnotes
# キーボードショートカット
- pymdownx.keys
# マーク・挿入・削除
- pymdownx.mark
- pymdownx.caret
- pymdownx.tilde
# SmartSymbols
- pymdownx.smartsymbols
# 追加の設定
extra:
version:
provider: mike
default: latest
analytics:
provider: google
property: G-XXXXXXXXXX
consent:
title: Cookie consent
description: >-
We use cookies to recognize your repeated visits and preferences, as well
as to measure the effectiveness of our documentation and whether users
find what they're searching for. With your consent, you're helping us to
make our documentation better.
social:
- icon: fontawesome/brands/github
link: https://github.com/username
- icon: fontawesome/brands/twitter
link: https://twitter.com/username
- icon: fontawesome/brands/linkedin
link: https://linkedin.com/in/username
generator: false
```
### デプロイメントとCI/CD設定
```yaml
# .github/workflows/docs.yml - GitHub Actions
name: Build and Deploy Documentation
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: "pages"
cancel-in-progress: false
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Setup Python
uses: actions/setup-python@v4
with:
python-version: '3.11'
- name: Cache pip dependencies
uses: actions/cache@v3
with:
path: ~/.cache/pip
key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
restore-keys: |
${{ runner.os }}-pip-
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install mkdocs-material
pip install mkdocs-git-revision-date-localized-plugin
pip install mkdocs-git-authors-plugin
pip install mkdocstrings[python]
pip install mkdocs-mermaid2-plugin
- name: Build documentation
run: |
mkdocs build --verbose --strict
- name: Setup Pages
uses: actions/configure-pages@v3
- name: Upload artifact
uses: actions/upload-pages-artifact@v2
with:
path: './site'
deploy:
if: github.ref == 'refs/heads/main'
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
needs: build
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v2
```
```bash
# 本番ビルドとデプロイメント
# 1. 依存関係のインストール
pip install -r requirements.txt
# requirements.txt例
cat > requirements.txt << EOF
mkdocs>=1.5.0
mkdocs-material>=9.0.0
mkdocs-git-revision-date-localized-plugin
mkdocs-git-authors-plugin
mkdocstrings[python]
mkdocs-mermaid2-plugin
pymdown-extensions
EOF
# 2. ローカル本番ビルドテスト
mkdocs build --strict --verbose
# 3. サイトの確認
ls -la site/
find site -name "*.html" | head -5
# 4. GitHub Pagesデプロイ
mkdocs gh-deploy --force
# 5. カスタムサーバーデプロイ
mkdocs build
rsync -avz --delete site/ [email protected]:/var/www/docs/
# 6. Dockerを使用したビルド
docker run --rm -v $(pwd):/docs squidfunk/mkdocs-material build
# 7. Netlifyデプロイ用設定
# netlify.toml
cat > netlify.toml << EOF
[build]
publish = "site"
command = "pip install -r requirements.txt && mkdocs build"
[build.environment]
PYTHON_VERSION = "3.11"
EOF
# 8. バージョン管理（mike使用）
pip install mike
mike deploy --push --update-aliases 1.0 latest
mike set-default --push latest
```