コンテンツにスキップ

MkDocsでMermaidダイアグラムを美しく表示する完全設定ガイド

この記事のポイント

  • フローチャート

    複雑な処理フローを視覚的に表現

  • シーケンス図

    システム間の相互作用を時系列で表示

  • ガントチャート

    プロジェクトスケジュールを管理

  • その他の図表

    クラス図、状態図、ER図など多様な表現

📖 はじめに

MkDocsでMermaidダイアグラムが表示されない問題に悩んでいませんか？

標準のMkDocsでは、````mermaid ブロックを書いてもコードブロックとして表示されるだけで、実際のダイアグラムは描画されません。本記事では、MkDocs Material テーマでMermaidダイアグラムを美しく表示するための完全な設定方法を解説します。

🔧 設定手順

Step 1: mkdocs.yml の設定

まず、mkdocs.yml ファイルを以下のように設定します：

# Markdown拡張設定
markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  # その他の拡張機能...

# JavaScript ライブラリの読み込み
extra_javascript:
  - https://unpkg.com/mermaid@10.9.0/dist/mermaid.min.js
  - javascripts/mermaid-init.js

Step 2: Mermaid初期化スクリプトの作成

docs/javascripts/mermaid-init.js ファイルを作成します：

// Mermaid initialization for MkDocs
document.addEventListener('DOMContentLoaded', function() {
    // Check if mermaid is loaded
    if (typeof mermaid !== 'undefined') {
        // Initialize mermaid with configuration
        mermaid.initialize({
            startOnLoad: true,
            theme: 'default',
            flowchart: {
                useMaxWidth: true,
                htmlLabels: true,
            },
            gitGraph: {
                theme: 'base',
                themeVariables: {
                    primaryColor: '#009688',
                    primaryTextColor: '#ffffff',
                    primaryBorderColor: '#00695c',
                    lineColor: '#757575',
                    secondaryColor: '#e0f2f1',
                    tertiaryColor: '#ffffff',
                }
            },
            sequence: {
                diagramMarginX: 50,
                diagramMarginY: 10,
                actorMargin: 50,
                width: 150,
                height: 65,
                boxMargin: 10,
                boxTextMargin: 5,
                noteMargin: 10,
                messageMargin: 35,
                wrap: false,
                mirrorActors: true,
                bottomMarginAdj: 1,
                useMaxWidth: true,
            }
        });

        // Support for dark mode
        const observer = new MutationObserver(function(mutations) {
            mutations.forEach(function(mutation) {
                if (mutation.type === 'attributes' && mutation.attributeName === 'data-md-color-scheme') {
                    const scheme = document.body.getAttribute('data-md-color-scheme');
                    const theme = scheme === 'slate' ? 'dark' : 'default';

                    // Re-initialize mermaid with new theme
                    mermaid.initialize({
                        startOnLoad: true,
                        theme: theme,
                        flowchart: {
                            useMaxWidth: true,
                            htmlLabels: true,
                        }
                    });

                    // Re-render all mermaid diagrams
                    const mermaidElements = document.querySelectorAll('.mermaid');
                    mermaidElements.forEach(function(element) {
                        element.removeAttribute('data-processed');
                    });
                    mermaid.init();
                }
            });
        });

        observer.observe(document.body, {
            attributes: true,
            attributeFilter: ['data-md-color-scheme']
        });
    }
});

Step 3: カスタムCSSの追加

docs/stylesheets/extra.css に以下のスタイルを追加：

/* Mermaid ダイアグラムのスタイル */
.mermaid {
  text-align: center;
  margin: 1.5rem 0;
  border-radius: 8px;
  background: var(--md-code-bg-color);
  padding: 1rem;
  overflow-x: auto;
}

/* ダークモード対応 */
[data-md-color-scheme="slate"] .mermaid {
  background: var(--md-default-bg-color);
  border: 1px solid var(--md-default-fg-color--lightest);
}

/* Mermaidダイアグラムの要素スタイル調整 */
.mermaid svg {
  max-width: 100%;
  height: auto;
}

.mermaid .node rect,
.mermaid .node circle,
.mermaid .node ellipse,
.mermaid .node polygon {
  fill: var(--md-primary-fg-color--light);
  stroke: var(--md-primary-fg-color);
  stroke-width: 2px;
}

.mermaid .node .label {
  color: var(--md-primary-bg-color);
  font-weight: 500;
}

.mermaid .edgeLabel {
  background-color: var(--md-default-bg-color);
  border-radius: 4px;
  padding: 2px 4px;
  font-size: 0.85rem;
}

/* フローチャートのスタイル */
.mermaid .flowchart-link {
  stroke: var(--md-primary-fg-color);
  stroke-width: 2px;
}

/* シーケンス図のスタイル */
.mermaid .actor {
  fill: var(--md-primary-fg-color--light);
  stroke: var(--md-primary-fg-color);
}

.mermaid .messageLine0,
.mermaid .messageLine1 {
  stroke: var(--md-primary-fg-color);
  stroke-width: 2px;
}

/* ガントチャートのスタイル */
.mermaid .task {
  fill: var(--md-primary-fg-color--light);
  stroke: var(--md-primary-fg-color);
}

/* レスポンシブ対応 */
@media (max-width: 768px) {
  .mermaid {
    margin: 1rem -1rem;
    border-radius: 0;
    padding: 1rem;
  }
}

🎨 使用例とサンプル

フローチャート

flowchart TD
    A[MkDocsサイト作成] --> B{Mermaid設定完了？}
    B -->|Yes| C[ダイアグラム表示成功]
    B -->|No| D[設定を確認]
    D --> E[mkdocs.yml修正]
    E --> F[JavaScript追加]
    F --> G[CSS追加]
    G --> B
    C --> H[🎉 完成！]

シーケンス図

sequenceDiagram
    participant U as ユーザー
    participant M as MkDocs
    participant J as Mermaid.js
    participant B as ブラウザ

    U->>M: ページを要求
    M->>B: HTMLを生成
    B->>J: Mermaidブロックを検出
    J->>J: ダイアグラムを描画
    J->>B: SVGを挿入
    B->>U: 完成したページを表示

ガントチャート

gantt
    title MkDocs Mermaid 設定プロジェクト
    dateFormat  YYYY-MM-DD
    section 設定フェーズ
    mkdocs.yml設定      :done, config, 2025-07-25, 1d
    JavaScript作成      :done, js, after config, 1d
    CSS追加             :done, css, after js, 1d
    section テストフェーズ
    動作確認            :active, test, after css, 1d
    ドキュメント作成    :doc, after test, 1d

クラス図

classDiagram
    class MkDocsConfiguration {
        +markdown_extensions: List
        +extra_javascript: List
        +extra_css: List
        +theme: MaterialTheme
        +setupMermaid()
    }

    class MermaidRenderer {
        +initialize()
        +renderDiagram()
        +handleDarkMode()
    }

    class MaterialTheme {
        +primary_color: String
        +accent_color: String
        +scheme: String
    }

    MkDocsConfiguration --> MermaidRenderer
    MkDocsConfiguration --> MaterialTheme

💡 設定のポイント

1. pymdownx.superfences の重要性

pymdownx.superfences はコードブロックを拡張するPython-Markdownの拡張機能です。custom_fences を設定することで、Mermaidブロックを特別扱いできます。

2. ダークモード自動切り替え

Material for MkDocsのダークモード切り替えに連動して、Mermaidのテーマも自動的に変更されます。

3. レスポンシブデザイン

モバイル端末でも美しく表示されるよう、CSSでレスポンシブ対応を実装しています。

🚀 高度な設定

カスタムテーマの作成

// カスタムテーマの例
mermaid.initialize({
    theme: 'base',
    themeVariables: {
        primaryColor: '#your-primary-color',
        primaryTextColor: '#your-text-color',
        primaryBorderColor: '#your-border-color',
        lineColor: '#your-line-color',
        // その他のカスタマイズ...
    }
});

特定の図表タイプの設定

// フローチャート専用の設定
flowchart: {
    diagramPadding: 8,
    htmlLabels: true,
    curve: 'basis',
    useMaxWidth: true,
}

⚠️ トラブルシューティング

よくある問題と解決策

  1. ダイアグラムが表示されない
  2. JavaScriptの読み込み順序を確認

  3. ブラウザの開発者ツールでエラーをチェック

  4. ダークモードで正しく表示されない

  5. MutationObserver の設定を確認

  6. CSS変数が正しく定義されているかチェック

  7. モバイルで表示が崩れる

  8. レスポンシブCSSの適用を確認
  9. useMaxWidth: true の設定を確認

📊 パフォーマンス最適化

CDN の選択

<!-- 推奨：安定版を指定 -->
<script src="https://unpkg.com/mermaid@10.9.0/dist/mermaid.min.js"></script>

<!-- 避ける：最新版（予期しない変更のリスク） -->
<script src="https://unpkg.com/mermaid/dist/mermaid.min.js"></script>

遅延読み込み

大量のダイアグラムがある場合は、Intersection Observer を使った遅延読み込みを検討してください。

🔗 まとめ

MkDocsでMermaidダイアグラムを表示するためには：

  1. pymdownx.superfences でカスタムフェンスを設定
  2. Mermaid CDN とカスタム初期化スクリプトを追加
  3. Material テーマに合わせたCSS を適用
  4. ダークモード対応 で統一感のあるデザインを実現

この設定により、技術文書の表現力が大幅に向上し、読者にとってより理解しやすいドキュメントが作成できます。

🔗 関連記事