MkDocsで日本語ドキュメントサイトを構築する設定ガイド

Posted at 2025-07-23

MkDocsで日本語ドキュメントサイトを構築する設定ガイド

はじめに

MkDocsは、Markdownファイルから静的なドキュメントサイトを簡単に作れるツールです。エンジニアだけでなく、非エンジニアでも扱いやすいのが特徴です。

この記事では、実際のプロジェクトで使っている「おすすめ設定例」と、その理由・便利な拡張機能について、初心者にもわかりやすく解説します。

基本設定

プロジェクト情報の設定

# Project information
site_name: My Documentation  # サイト名
site_url: https://example.com  # サイトのURL
site_description: プロジェクトの説明文を記載します。  # サイトの説明
site_author: 作成者名  # サイトの作成者
repo_url: https://github.com/username/repository  # リポジトリのURL
repo_name: Repository Name  # リポジトリ名

# Copyright
copyright: 'Copyright © 2025 作成者名. All rights reserved.'  # 著作権情報

設定例の説明：

site_name: ブラウザのタイトルバーに表示される名前
site_url: 本番環境のURL（必須ではないが、サイトマップ生成時に使用）
repo_url: GitHubのリポジトリURLを設定すると、自動でリンクが生成される

プラグイン設定

日本語検索対応

plugins:
  - search:
      lang: 'ja'  # 検索プラグインの言語設定を日本語に

おすすめ理由: 日本語の全文検索ができるようになり、ドキュメントが多くなってもすぐに目的の情報を探せます。

Markdownファイルのインクルード

  - include-markdown:
      encoding: utf-8  # ファイルのエンコーディング
      preserve_includer_indent: false  # インクルード元のインデントを保持するか
      dedent: true  # インクルード内容のインデントを削除するか
      trailing_newlines: true  # 末尾の改行を保持するか
      comments: true  # コメントを保持するか
      rewrite_relative_urls: true  # 相対URLを再書き換えするか

使用例：

<!-- 他のMarkdownファイルをインクルード -->
{%
   include-markdown "common/header.md"
%}

おすすめ理由: 複数のMarkdownファイルをまとめて管理できるので、共通ヘッダーやフッター、再利用したい説明文などを一箇所で管理できます。

テーブル表示の強化

  - table-reader  # CSVファイルからテーブルを生成

使用例：

<!-- CSVファイルをテーブルとして表示 -->
{{ read_csv('data/sample.csv') }}

おすすめ理由: CSVファイルをそのままMarkdownにテーブル表示できるので、データの更新や管理がとても楽です。

図表生成（Kroki）

  - kroki  # 様々な図表を生成

使用例：

```mermaid
graph TD
    A[開始] --> B{条件}
    B -->|Yes| C[処理1]
    B -->|No| D[処理2]
    C --> E[終了]
    D --> E
\`\`\`
\`\`\`

#### Krokiとは？

Krokiは、さまざまな図表（UML、シーケンス図、フローチャートなど）をMarkdown内で簡単に描画できるサービスです。MermaidやPlantUMLなど複数の記法に対応しています。

#### Mermaidとは？

Mermaidは、テキストでフローチャートやシーケンス図などを記述できる記法です。コードブロック内に`mermaid`と書くだけで、図が自動生成されます。

> **なぜおすすめ？**
>
> - **設計書や仕様書に図を入れたいとき**、画像を用意しなくてもテキストで管理できるので、修正やバージョン管理がとても楽です。
> - GitHubや多くのドキュメントツールでもサポートされており、チームでの共有にも最適です。
> - Krokiを使うとMermaid以外の記法（PlantUML、Graphvizなど）も同じように使えます。

## テーマ設定（Material Design）

```yaml
theme:
  name: material  # Material Designテーマを使用
  language: ja  # サイトの言語を日本語に設定
  logo: images/logo.svg  # サイトのロゴ
  favicon: images/favicon.ico  # サイトのファビコン
  features:
    - navigation.tabs  # ナビゲーションにタブを使用
    - navigation.top  # トップナビゲーションを有効化
    - navigation.sections  # セクションごとのナビゲーション
    - navigation.tracking  # ナビゲーションのトラッキング
  palette:
    scheme: light  # カラースキーム（ライトモード）
    primary: indigo  # プライマリカラー
    accent: amber  # アクセントカラー

カラーオプション例：

Primary: 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
Accent: red, pink, purple, deep purple, indigo, blue, light blue, cyan, teal, green, light green, lime, yellow, amber, orange, deep orange

おすすめ理由: Materialテーマは見た目が美しく、スマホでも見やすいレスポンシブ対応。カスタマイズ性も高く、企業サイトやチーム内ドキュメントにも最適です。

Markdown拡張機能

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.details  # 詳細表示をサポート
  - admonition  # 注意書きやヒントを表現
  - def_list  # 定義リストをサポート
  - codehilite:  # コードハイライトを有効化
      guess_lang: false  # 言語の自動判定を無効化
      use_pygments: true  # Pygmentsを使用してコードをハイライト

使用例：

Admonition（注意書き）

!!! note "メモ"
    これは重要な情報です。

!!! warning "警告"
    この操作は注意が必要です。

!!! tip "ヒント"
    より効率的な方法があります。

おすすめ理由: 注意やヒントを目立たせることで、読者が重要なポイントを見逃しにくくなります。

Details（折りたたみ）

??? example "例を表示"
    ここに詳細な例を記載します。
    通常は折りたたまれています。

???+ info "デフォルトで開く"
    この内容はデフォルトで展開されます。

おすすめ理由: ページが長くなっても、補足情報を折りたたんでスッキリ見せられます。

定義リスト

用語1
:   用語1の説明

用語2
:   用語2の説明
    複数行での説明も可能です。

おすすめ理由: 用語集やFAQなど、説明を整理して書きたいときに便利です。

ナビゲーション設定

nav:
  - ホーム: index.md
  - ガイド:
      - 基本情報: guide/basic.md
      - 詳細設定: guide/advanced.md
      - トラブルシューティング: guide/troubleshooting.md
  - API リファレンス:
      - 概要: api/overview.md
      - エンドポイント:
          - ユーザー管理: api/users.md
          - データ管理: api/data.md
  - 設計書:
      - アーキテクチャ: design/architecture.md
      - データベース: design/database.md

ナビゲーション設定のコツ：

階層は最大3-4レベルまでに留める
関連する内容はグループ化する
ファイルパスはdocs/フォルダからの相対パス

おすすめ理由: 階層を深くしすぎないことで、迷子になりにくく、誰でも直感的に使えるサイトになります。

JavaScript・CSS拡張

DataTablesの設定例

extra_javascript:
  - https://code.jquery.com/jquery-3.7.1.min.js
  - https://cdn.datatables.net/1.13.8/js/jquery.dataTables.min.js
  - https://cdn.datatables.net/buttons/2.4.2/js/dataTables.buttons.min.js
  - https://cdn.datatables.net/buttons/2.4.2/js/buttons.html5.min.js  # Excel出力用
  - js/custom.js  # カスタムJavaScript

extra_css:
  - https://cdn.datatables.net/1.13.8/css/jquery.dataTables.min.css
  - https://cdn.datatables.net/buttons/2.4.2/css/buttons.dataTables.min.css
  - css/custom.css  # カスタムCSS

おすすめ理由: DataTablesを使うと、表をソート・検索・エクスポート（Excel出力など）できるようになり、データ閲覧がとても便利になります。

カスタムJavaScriptの例（js/custom.js）

document.addEventListener('DOMContentLoaded', function() {
    // DataTablesの初期化
    $('.data-table').DataTable({
        language: {
            url: 'https://cdn.datatables.net/plug-ins/1.13.8/i18n/ja.json'
        },
        dom: 'Bfrtip',
        buttons: [
            'copy', 'csv', 'excel', 'print', 'colvis'
        ],
        pageLength: 25,
        responsive: true
    });
});

カスタムCSSの例（css/custom.css）

/* テーブルのスタイル調整 */
.md-typeset table:not([class]) {
    font-size: 0.8rem;
}

/* コードブロックの調整 */
.md-typeset pre > code {
    font-size: 0.75rem;
}

/* ナビゲーションの調整 */
.md-nav__item--nested > .md-nav__link {
    font-weight: bold;
}

ディレクトリ構成例

project/
├── mkdocs.yml          # MkDocs設定ファイル
├── docs/              # ドキュメントファイル
│   ├── index.md       # トップページ
│   ├── guide/         # ガイドセクション
│   ├── api/           # APIドキュメント
│   ├── css/           # カスタムCSS
│   ├── js/            # カスタムJavaScript
│   └── images/        # 画像ファイル
└── site/              # 生成されるサイト（gitignore推奨）

おすすめ理由: ディレクトリを分けておくことで、ファイルが増えても管理しやすく、チーム開発でも迷いません。

よく使用するコマンド

# 開発サーバーの起動
mkdocs serve

# ホットリロード有効でサーバー起動
mkdocs serve --dev-addr=127.0.0.1:8000

# サイトのビルド
mkdocs build

# GitHub Pagesへのデプロイ
mkdocs gh-deploy

まとめ

この設定例とおすすめ拡張機能を使えば、

日本語で全文検索できるドキュメントサイト
スマホでも見やすい美しいデザイン
データを簡単にテーブル表示・エクスポート
テキストで管理できる図やフローチャート
注意・ヒント・FAQなども見やすく整理

といった「実用的で管理しやすい」サイトが誰でも作れます。

特に企業やチームでの情報共有・ナレッジ管理に最適です。
ぜひ自分のプロジェクトにも取り入れてみてください！

参考リンク

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up

MkDocsで日本語ドキュメントサイトを構築する設定ガイド

MkDocsで日本語ドキュメントサイトを構築する設定ガイド

はじめに

基本設定

プロジェクト情報の設定

プラグイン設定

日本語検索対応

Markdownファイルのインクルード

テーブル表示の強化

図表生成（Kroki）

Markdown拡張機能

おすすめ拡張機能とその理由

Admonition（注意書き）

Details（折りたたみ）

定義リスト

ナビゲーション設定

JavaScript・CSS拡張

DataTablesの設定例

カスタムJavaScriptの例（js/custom.js）

カスタムCSSの例（css/custom.css）

ディレクトリ構成例

よく使用するコマンド

まとめ

参考リンク