Mermaid ダイアグラム コードガイド｜テキストから図を自動生成

Mermaid の基本概念とバージョン 11+ の特徴

テキストベースのダイアグラム作成ツールとして、Mermaid は 2026 年現在、開発ドキュメントおよび技術資料において事実上の標準規格となっています。従来の画像形式（PNG, SVG）で図を作成し保存する手法は、バージョン管理システム上での差分確認が困難であり、修正コストが高いという課題を抱えていました。しかし、Mermaid を採用することで、Markdown ファイル内で直接記述することが可能となり、Git による変更履歴の追跡や、CI/CD プロセスにおける自動検証が可能になります。これは「Diagrams as Code」という概念の実践的な例であり、開発ライフサイクル全体において可読性と保守性を劇的に向上させる技術です。

特に Mermaid.js のバージョン 11（Mermaid v11）は、2025 年にリリースされた主要アップデート以降、レンダリングエンジンが大幅に刷新されています。これにより、SVG ベースの描画パフォーマンスが改善され、数百万ノード規模の複雑な図でもブラウザ上でスムーズに描画できるようになりました。また、CSS スタイルのカスタマイズ性が強化され、企業のブランディングカラーやテーマ設定（Dark Mode 対応）をダイアグラム内に直接埋め込むことができるようになりました。バージョン 11 では、JavaScript の埋め込みスクリプトによる動的なデータバインディングにも対応し、固定された静的図から、リアルタイムデータに基づくインタラクティブな図へと進化を遂げています。

開発者にとって Mermaid を理解することは、技術ドキュメントの品質向上に直結します。2026 年時点の主要ツールチェーンにおいて、Mermaid のネイティブサポートはほぼ標準化されています。GitHub が README ファイルでの Mermaid レンダリングを正式にサポートして以来、オープンソースプロジェクトの標準的な運用パターンとなりました。また、Obsidian や VS Code などのローカルエディタでも、拡張機能なしであるいは軽量な設定で動作するようになり、オフライン環境下での開発効率も向上しています。本ガイドでは、Mermaid v11 の最新機能を踏まえつつ、実務ですぐに活用できるコード記法と統合方法を詳しく解説していきます。

フローチャートの詳細記法（graph, サブグラフ，スタイル）

フローチャートは、Mermaid で最も頻繁に使用される図の一種であり、ロジックの流れやプロセスを視覚化する際に不可欠です。基本的な記述形式は graph と指定し、その後に方向性を定義します。例えば、graph TD は Top-Down（上から下へ）、graph LR は Left-Right（左から右へ）のレイアウトになります。各ノードは文字列で定義され、エッジ（矢印）で接続されます。2026 年版の Mermaid v11 では、ノードの形状がさらに細かく制御可能となり、円形、四角形、多角形に加え、データセンターやサーバーなどのアイコンを組み合わせた複雑な形状もサポートしています。以下に基本的な記述例を示します。

graph TD
    A[開始] --> B{条件判定}
    B -->|真| C[処理 A]
    B -->|偽| D[処理 B]
    C --> E[終了]
    D --> E

この記法において、A[開始] の形式は、ID を指定し角括弧でラベルを定義するものです。エッジの方向を示す矢印 --> は、条件付きの実行経路を表現するために使用されます。|真| や |偽| はエッジに付与されるラベルであり、分岐の理由や結果を視覚的に補完します。また、Mermaid v11 では、エッジの種類も多様化しており、実線だけでなく点線（-.->）、破線、カーブ付きの矢尾など、状況に応じた表現が可能になりました。これにより、エラーフローや非同期処理などの特殊な流れを直感的に表現できます。

複雑なロジックを扱う場合、サブグラフ（Subgraph）機能を活用して論理的なグループ化を行います。これは、関連するノードを一つの枠線で囲むことで、視認性を高める役割を果たします。例えば、認証プロセスの一部を「Authentication Layer」というサブグラフに囲むことで、システムアーキテクチャにおける層ごとの役割を明確にできます。さらに、style 属性や classDef を使用して特定のノードのスタイルを変更することも可能です。色（fillColor）、枠線の太さ（strokeWidth）、フォントサイズなどの指定は、ドキュメントの統一感を保つために重要です。以下にサブグラフとスタイルを組み合わせた高度な記法例を示します。

graph TD
    subgraph Auth [Authentication Layer]
        A[ログイン画面] --> B{認証成功？}
        B -->|Yes| C[セッション生成]
        B -->|No| D[エラー表示]
    end
    
    subgraph App [Application Layer]
        C --> E[ユーザーダッシュボード]
        D --> F[再試行ボタン]
    end

    classDef error fill:#f96,stroke:#333,stroke-width:2px;
    class D error;

このコード例では、subgraph Auth [Authentication Layer] によってノード A から D が論理的なブロックにまとめられています。下部の classDef は CSS クラス定義と類似しており、特定のクラス（ここでは error）を持つノードに対してスタイルを適用します。fill:#f96 は赤みがかった色を指定し、エラー状態の視覚的な強調に効果的です。2025 年以降の実装では、外部 CSS ファイルから Mermaid のスタイルを読み込む機能も強化され、プロジェクト全体のデザインガイドラインと自動連動する仕組みが標準装備されています。これにより、個別の図ごとの手動スタイリングを減らし、保守コストを削減することが可能になっています。

シーケンス図とクラス図の実装パターン

シーケンス図は、システム間のメッセージフローや時間軸に沿った処理順序を表現するために使用されます。特に、ユーザーエクスペリエンス（UX）の設計や、API 呼び出しのタイミングを可視化する際に有用です。Mermaid の sequenceDiagram は、参加者（Actor）とメッセージ（Message）を明確に定義する構造を持っています。2026 年の最新バージョンでは、アクティブな期間を示す矩形（Activate/Deactivate）だけでなく、パラメータ付きのメッセージや、非同期通信の表現もより詳細に行えるようになりました。

sequenceDiagram
    participant User as ユーザー
    participant Frontend as フロントエンド
    participant API as API サーバー
    participant DB as データベース

    User->>Frontend: ログインリクエスト送信
    activate Frontend
    Frontend->>API: POST /auth/login
    activate API
    API->>DB: ユーザー情報照会
    activate DB
    DB-->>API: ユーザーデータ返却
    deactivate DB
    API-->>Frontend: 認証トークン返却
    deactivate API
    Frontend-->>User: ダッシュボード表示
    deactivate Frontend

この例では、participant キーワードで各コンポーネントを定義し、矢印 ->> で非同期（または同期）のメッセージフローを示しています。activate と deactivate は、特定の処理が実行されている期間を矩形で表示するもので、リソース使用量の可視化やボトルネック特定に役立ちます。また、破線の戻り値 -->> を使用することで、レスポンスの流れを区別することもできます。2026 年版 Mermaid では、メッセージのラベル（例：ログインリクエスト送信）だけでなく、HTTP リクエストボディの一部やヘッダー情報を記述する機能も追加され、技術ドキュメントとしての精度が向上しています。

クラス図は、オブジェクト指向設計におけるクラスの構造と関係性を表現します。Mermaid の classDiagram では、継承（extends）、実装（implements）、アソシエーションなどの関係を定義できます。2025 年以降のバージョンでは、アクセス修飾子（パブリック、プライベートなど）やデータ型の指定がより柔軟に行えるようになりました。これにより、データベーススキーマからコード構造を逆算する際にも使用可能です。

classDiagram
    class Animal {
        +String name
        +int age
        +move()
    }
    
    class Dog {
        +String breed
        +bark()
    }

    class Cat {
        +String color
        +meow()
    }

    Animal <|-- Dog : 継承
    Animal <|-- Cat : 継承
    
    note "基本動作は共通" for Animal

この記法では、Animal が基底クラスとなり、Dog と Cat がそのサブクラスとして定義されています。<|-- は「継承」の矢印であり、note コマンドで注釈を追加することで、設計意図を補足できます。Mermaid v11 では、これらのクラス定義が HTML5 Canvas ベースでの描画にも対応し、ドキュメント内でのインタラクション（ホバー時の詳細表示など）が可能になりました。これにより、静的なドキュメントから、開発者が直接操作してクラス関係を探索できるツールへと進化しています。

ER 図によるデータベース設計の可視化

ER 図（Entity-Relationship Diagram）は、データベーススキーマの設計を視覚化する重要な手段です。Mermaid の erDiagram モードを使用すると、エンティティ間の関係性を直感的に表現できます。2026 年時点では、リレーショナルデータベースだけでなく、NoSQL やドキュメント型データベースの構造も記述可能となりました。特に、主キー（PK）と外部キー（FK）の明示的な表記や、結合条件の視覚化が標準機能として強化されています。

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ ORDER-ITEM : contains
    PRODUCT ||--o{ ORDER-ITEM : includes
    
    CUSTOMER {
        int customer_id PK
        string name
        string email
        date created_at
    }

    ORDER {
        int order_id PK
        int customer_id FK
        decimal total_price
        status order_status
    }
    
    PRODUCT {
        int product_id PK
        string product_name
        int stock_quantity
        price unit_price
    }

この記法では、||--o{ のような特殊な矢印で結合の度合い（カーディナリティ）を表現しています。|| は必須（1 つ）、o{ は任意（0 以上複数）を意味します。これは「カスタマーが 1 人以上、注文は多数」のようなビジネスルールの可視化に役立ちます。Mermaid v11 では、これらの関係記号のバリエーションがさらに細かく定義されており、1:1、1:N、M:N のすべての組み合わせを正確に描画できます。また、PK や FK の指定により、データベース設計者がキー制約を視覚的に確認できるようになりました。

ER 図におけるフィールドの詳細記述も重要です。各エンティティ内のブロック定義では、データ型（int, string, decimal など）と属性名（customer_id, name など）を明確に区別して記述します。2026 年版の Mermaid では、このブロック内でのコメント入力や、特定のフィールドに対する制約（NOT NULL, UNIQUE など）の表記もサポートされており、設計段階でエラーを防ぐ役割を果たしています。さらに、ER 図から SQL スクリプトを生成する機能（Mermaid-to-SQL）が公式プラグインとして提供されるようになり、設計から実装までの流れを自動化することも可能です。

ガントチャート・状態遷移図・パイチャートの活用

プロジェクト管理においては、ガントチャートが必須のツールです。Mermaid の gantt モードを使用することで、タスクのスケジュール、依存関係、マイルストーンを視覚化できます。2026 年の最新バージョンでは、リソース割り当てや負荷可視化も可能になり、プロジェクトマネージャーにとって強力な意思決定支援ツールとなっています。

gantt
    title プロジェクト開発スケジュール（2026 年）
    dateFormat  YYYY-MM-DD
    section デザインフェーズ
    UI/UX 設計      :a1, 2026-01-01, 30d
    仕様定義        :after a1, 20d
    
    section 開発フェーズ
    フロントエンド実装 :active, dev1, after a1, 45d
    API 設計         :dev2, parallel to dev1, 20d
    
    section マイルストーン
    リリース準備      :milestone, m1, 2026-03-01, 0d

この例では、title でチャートのタイトルを指定し、section でフェーズをグループ化します。active キーワードは、現在進行中のタスクを示すハイライトに使用されます。さらに、parallel to を使うことで並行処理の可視化が可能になり、リソース競合を防ぐ効果もあります。2026 年時点では、このガントチャートを Jira や Asana と同期する機能も実装されており、リアルタイムで進捗を反映させることが可能です。

状態遷移図は、オブジェクトやシステムのライフサイクルを追跡するために使用されます。stateDiagram-v2 を用いることで、システムが特定のトリガーに応じてどのように状態を変化させるかを表現できます。例えば、認証フローやステータス管理ロジックの可視化に役立ちます。

stateDiagram-v2
    [*] --> 未登録
    未登録 --> 入力中: ユーザー開始
    入力中 --> 確認中: 送信
    確認中 --> 完了: OK
    確認中 --> 未登録: NG
    完了 --> [*]

この記法では、[*] が初期状態と終端状態を表します。矢印のラベル（例：ユーザー開始）が遷移トリガーとなります。Mermaid v11 では、状態の入れ子構造や、状態内のアクション定義も可能になりました。これにより、複雑なビジネスロジックを簡潔にドキュメント化できます。

パイチャートは、データの割合や構成比を示すために使用されます。pie モードで簡単に作成可能です。例えば、プロジェクト予算の配分率や、技術スタックの使用頻度などを可視化する際に役立ちます。2025 年以降は、3D パイチャートのレンダリングオプションも追加され、プレゼンテーション資料としての魅力が向上しています。

GitHub / Obsidian / VS Code での統合と運用

Mermaid の真価は、開発ツールとの堅牢な統合によって発揮されます。GitHub は公式に Mermaid レンダリングをサポートしており、README ファイルや Pull Request コメント、Issue 内でダイアグラムを表示できます。これにより、コードレビュープロセスにおいて、アーキテクチャ図を共有する際の障壁が取り除かれました。2026 年現在では、GitHub Actions を使用して Mermaid 記法のスキャンとバリデーションを行うワークフローも標準化されています。

# GitHub Actions (CI/CD) の例：Mermaid スキーマ検証
name: Validate Diagrams
on: push
jobs:
  validate-mermaid:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Mermaid CLI
        run: npm install -g @mermaid-js/mermaid-cli
      - name: Validate Diagrams
        run: |
          mmdc -i docs/architecture.mmd -o output.png --configFile mermaid-config.json || exit 1

このワークフローでは、@mermaid-js/mermaid-cli を使用してローカル環境でのレンダリングテストを行い、エラーが発生した場合は CI を失敗させます。これにより、ドキュメントの破損や記述ミスが本番環境にリークするのを防ぎます。また、Mermaid Live Editor の URL を埋め込むことで、ブラウザ上で即座にプレビューすることも可能です。

ローカル開発環境では、Obsidian や VS Code でのサポートが充実しています。Obsidian では「Mermaid」という公式プラグインをインストールすることで、Markdown ファイル内の Mermaid コードブロックをリアルタイムでレンダリングできます。2026 年版の設定では、mermaid-config.json をプロジェクトルートに配置することで、フォントや色テーマを一括管理可能です。

// Obsidian / VS Code の mermaid-config.json
{
    "theme": "base",
    "themeVariables": {
        "primaryColor": "#007bff",
        "fontSize": 14,
        "fontFamily": "Noto Sans JP"
    },
    "securityLevel": "loose"
}

この設定ファイルでは、themeVariables を使用してテーマのカラーやフォントサイズを詳細に制御しています。VS Code では「Markdown Preview Mermaid Support」などの拡張機能を使用しますが、2026 年版の拡張機能では、エディタ内で直接編集可能なプロパティパネルが実装されており、矢印の色や太さをマウス操作で変更できる機能が追加されています。

Notion での利用も可能です。Notion のブロックに Mermaid コードを貼り付けることで、ページ内に図を表示できます。ただし、Notion のセキュリティ設定によってはスクリプトの実行制限がある場合があり、その場合は静的な SVG としてエクスポートして埋め込む必要があります。Mermaid Live Editor（https://mermaid.live）は、ブラウザベースの統合環境であり、コード編集とプレビューが同時に表示されるため、学習やデバッグに最適です。2026 年版では、コピペ機能や URL 共有機能が強化され、チームでの共同レビューもスムーズに行えるようになりました。

比較表によるツール・スキーム選定支援

各ツールのサポート状況や機能の違いを整理することで、プロジェクト環境に適した Mermaid の活用方法を決定できます。以下の比較表は、主要なプラットフォームにおける Mermaid のサポートレベルと特徴を示しています。

GitHub は最も堅牢なサポートを提供しており、バージョン管理との親和性が抜群です。Obsidian と VS Code はローカル環境での開発に優れており、オフラインでも作業可能です。Notion はドキュメントの共有には便利ですが、複雑な図の作成には制約があります。Mermaid Live Editor は学習やデバッグに最適で、2026 年版では AI による自動記述支援機能も追加されています。

また、図の種類ごとの適性も考慮する必要があります。以下は、各ダイアグラム種類の難易度と推奨ユースケースを比較した表です。

よくある質問（FAQ）

Q1. GitHub の README で Mermaid が表示されないのはなぜですか？ A1. 基本的には Mermaid コードブロックが正しく記述されているか確認してください。通常は mermaid ... という形式で囲みます。また、GitHub 側でのキャッシュクリアやブラウザの再読み込みを試みてください。2026 年版では、特定の特殊文字（例：&）を含む場合、エスケープ処理が必要になることがあります。

Q2. Mermaid v11 と v9 の互換性はありますか？ A2. 基本的には後方互換性を維持していますが、一部の新機能やスタイル指定は旧バージョンでは動作しない可能性があります。特に classDef や CSS 連携部分で差異が出るため、プロジェクトの Mermaid バージョンを統一することが推奨されます。

Q3. Obsidian で Mermaid がレンダリングされない場合はどうすれば？ A3. 「Mermaid」プラグインがインストールされているか確認してください。設定画面から「Render on Load」を有効化すると、エディタ内で即時表示されます。また、キャッシュクリアや再起動も有効な対策です。

Q4. 矢印の太さや色を変更したい場合、どのように記述しますか？ A4. classDef を使用してクラス定義を作成し、strokeWidth, stroke, fillColor などの属性を指定します。例：classDef myStyle fill:#f96,stroke:#333,stroke-width:2px; class nodeID myStyle;

Q5. 大量のノードがあるフローチャートで描画が重いですが対策は？ A5. メッシュサイズが大きくなる場合は、サブグラフを活用して論理的に分割してください。また、Mermaid v11 のレンダリングエンジン設定で renderingMode: 'svg' を指定し、ブラウザのキャパシティに合わせて調整することも可能です。

Q6. ガントチャートでタスクの日付が正しく表示されません。 A6. dateFormat が指定されているか確認してください。通常は YYYY-MM-DD 形式を使用します。また、タスク名の前に日付を記述するのではなく、task: start_date, duration の形式に従って記述する必要があります。

Q7. VS Code で Mermaid プレビューが動かない原因は？ A7. 「Markdown Preview Mermaid Support」拡張機能が有効化されているか確認してください。また、設定ファイルで mermaid.js のパスが正しく指定されているかチェックしてください。最新バージョンの拡張機能をアップデートすることで解決することが多いです。

Q8. エラーメッセージ「Unexpected token」が表示されます。 A8. 構文エラーの可能性が高いです。各ノード間の接続記号（例：-->）や、エスケープ文字の使用を確認してください。特に特殊文字を含むラベルを使う際は、二重引用符 "" で囲むか、バッククォート ` を使用して囲む必要があります。

Q9. 状態遷移図でループ処理を表現したいです。 A9. 矢印を自身に返す形で記述するか、--> の矢印を曲げてループの形を作ります。Mermaid v11 では自動的にループ形状を最適化する機能も実装されており、単純な自己参照でも自然な描画が可能です。

Q10. 外部 CSS ファイルから Mermaid のスタイルを読み込めますか？ A10. はい、可能です。Mermaid v11 では init コマンドで設定を読み込むことができますが、セキュリティレベルによってはローカルファイルの読み込み制限がある場合があります。その場合は、JSON コンフィグファイル（mermaid-config.json）を使用することを推奨します。

まとめ

本ガイドでは、2026 年時点での Mermaid ダイアグラム作成の最新知識と実践手法を網羅的に解説しました。テキストベースで図を作成する「Diagrams as Code」の概念は、開発プロセスにおいてドキュメントの鮮度と正確性を担保するための重要な技術です。Mermaid.js v11 の機能強化により、フローチャートやシーケンス図の表現力が高まり、ER 図やガントチャートといった複雑な図も容易に扱えるようになりました。

以下の要点を念頭に置き、実践に活かしてください。

• バージョン管理: Mermaid v11 の新機能を積極的に活用し、プロジェクト内で統一された記法を採用する。
• ツール統合: GitHub Actions を用いた CI 検証を導入し、ドキュメントの品質を保証する。
• スタイル設計: classDef や CSS 連携により、視覚的な一貫性を保ちつつ、重要な情報への注目を促す。
• 学習と共有: Mermaid Live Editor を活用してチーム内で図の確認を行い、共通認識を形成する。

Mermaid は単なる図作成ツールではなく、開発コミュニケーションの基盤です。本ガイドの内容を踏まえ、より効果的な技術ドキュメント作成を実現してください。