【コピペで動く】Markdown Mermaid記法の書き方チートシート｜フローチャート・シーケンス図・ER図実例集

Markdown（マークダウン）でシステム設計書、要件定義書、API仕様書、README、技術ブログを執筆していると、 「図やフローチャートを使って視覚的にわかりやすく伝えたい」 という場面に頻繁に遭遇します。しかし、一般的な作図ソフトで画像を作ると、仕様変更のたびに再書き出しや再アップロードが必要になり、Gitでの差分比較もできません。

そんな課題を完璧に解決するのが、テキストコードだけで綺麗なダイアグラムを描画できるオープンソースライブラリ 「Mermaid（マーメイド）」 です。本記事は、業務中にサッと参照してそのままコピー＆ペーストで即動作する 「Mermaid書き方完全チートシート」 です。フローチャートやシーケンス図の最速テンプレートから、ノード形状・矢印記号の一覧表、主要エディタでのプレビュー設定、日本語エラーの回避術、生成AIプロンプトまで網羅しています。

【最速コピペ】Mermaidの基本構文とすぐ使える2大テンプレート

Mermaid（マーメイド）の書き方はとてもシンプルです。 Markdownのコードブロック記法 と同様に、バッククォート3つ（```）の直後に mermaid と指定し、ブロック内にダイアグラム構文を記述します。

```mermaid
[ここに図の種類とMermaid構文を記述]
```

まずは、実務ドキュメントで最も利用頻度が高い 「フローチャート」 と 「シーケンス図」 の最小テンプレートを紹介します。以下のコード枠右上のボタンからコピーして、エディタに貼り付けてみてください。

① フローチャートの最小サンプルコード＆出力プレビュー

開始から処理、条件分岐（Yes / No）、終了までの一連の流れをコンパクトに表現した基本フローチャートです。

```mermaid
flowchart TD
    Start(["開始"]) --> Process["データを受信して検証"]
    Process --> Condition{"入力内容は正常？"}
    Condition -->|Yes| Success["保存処理を実行"]
    Condition -->|No| Error["エラーメッセージを表示"]
    Success --> Finish(["終了"])
    Error --> Finish
```

② シーケンス図の最小サンプルコード＆出力プレビュー

ユーザー、Webサーバー、データベース間のリクエストとレスポンス（時系列のやり取り）を表した最小シーケンス図です。

```mermaid
sequenceDiagram
    autonumber
    actor User as ユーザー
    participant Web as Webサーバー
    participant DB as データベース

    User->>Web: ログインリクエスト送信
    Web->>DB: ユーザー認証情報を検索
    DB-->>Web: 認証結果（一致データ）を返却
    Web-->>User: ログイン成功・トークン返却
```

【早見表】Mermaidで使える全ダイアグラム宣言キーワード一覧

Mermaidでは、コードブロックの1行目に 「ダイアグラム種別の宣言キーワード」 を記述するだけで、目的の図表を自動生成できます。利用可能な主要ダイアグラムと宣言キーワードの一覧をまとめました。

※以前のバージョンで使われていた graph 宣言も動作しますが、最新のスタイル機能やサブグラフ記法に対応した flowchart の使用が公式で強く推奨されています。

【コピペ用】フローチャート（flowchart / graph）の書き方完全チートシート

フローチャートは、システム設計書や業務マニュアルで最も使用頻度が高いダイアグラムです。向きの制御、ノード形状の使い分け、線の種類、条件分岐、サブグラフ、色付けまでを体系的にチートシート化しました。

グラフの向き指定（TD/TB: 上から下、LR: 左から右、RL: 右から左、BT: 下から上）

flowchart の直後に半角スペースを空けて向きのアルファベット2文字を指定します。

```mermaid
flowchart LR
    A["ステップ1（左）"] --> B["ステップ2（中央）"] --> C["ステップ3（右）"]
```

ノードの形状一覧（長方形 [ ]、角丸 ( )、ひし形 { }、円 (( ))、サブルーチン [[ ]]、円柱 DB [( )]、非対称 > ]）

ノードIDの直後に配置する括弧の記号を変えるだけで、JIS規格やUMLに準拠した様々な図形を即座に描画できます。

```mermaid
flowchart TD
    N1(["開始・終了：スタジアム"])
    N2["通常処理：四角"]
    N3{"条件分岐：ひし形"}
    N4[("DBストレージ：円柱")]
    N5[["外部関数：二重枠"]]
    N6>"通知メッセージ：フラグ"]

    N1 --> N2 --> N3
    N3 -->|Yes| N4
    N3 -->|No| N5
    N4 --> N6
```

線の種類とテキスト（実線 –>、破線 -.->、太線 ==>、矢印なし —、テキスト付き — テキスト –>）

ノード間をつなぐコネクタ（線・矢印）にも多彩なバリエーションが存在します。条件テキストは -->|テキスト| または -- テキスト --> のどちらでも記述可能です。

```mermaid
flowchart LR
    A1["実線"] --> B1["通常"]
    A2["条件"] -->|Yes| B2["承認"]
    A3["太線"] ==> B3["メイン"]
    A4["破線"] -.-> B4["非同期"]
    A5["双方向"]  B5["同期"]
```

条件分岐とサブグラフ（subgraph）の実践コード

複数のノードを「フロントエンド」「APIサーバー」「DB」のようにグループ枠で整理したい場合は subgraph 構文を使います。

```mermaid
flowchart TB
    subgraph Client["クライアント環境"]
        Browser["Webブラウザ (React)"]
        Mobile["モバイルアプリ (Flutter)"]
    end

    subgraph Backend["バックエンドシステム"]
        Gateway["API Gateway (Kong)"]
        AuthService["認証サービス"]
        OrderService["注文受付サービス"]
    end

    subgraph DataStore["データ永続化層"]
        MainDB[("PostgreSQL メインDB")]
        CacheStore[("Redis セッション")]
    end

    Browser -->|HTTPS / JSON| Gateway
    Mobile -->|HTTPS / JSON| Gateway
    Gateway -->|トークン検証| AuthService
    Gateway -->|注文作成| OrderService
    AuthService --> CacheStore
    OrderService --> MainDB
```

色・デザインのカスタマイズ（style / classDef）

ノードの背景色や枠線の色を変えることで、視認性を劇的に高めることができます。個別ノードに適用する style と、共通クラスを定義して使い回す classDef があります。

```mermaid
flowchart LR
    %% クラス定義（背景色 fill、枠線 stroke、文字色 color）
    classDef success fill:#d4edda,stroke:#28a745,stroke-width:2px,color:#155724;
    classDef danger fill:#f8d7da,stroke:#dc3545,stroke-width:2px,color:#721c24;
    classDef primary fill:#cce5ff,stroke:#004085,stroke-width:2px,color:#004085;

    Start(["処理開始"]):::primary --> Check{"データ整合性チェック"}
    Check -->|正常| OK["登録完了 (200 OK)"]:::success
    Check -->|不正| NG["エラー返却 (400 Error)"]:::danger
```

【コピペ用】シーケンス図（sequenceDiagram）の書き方完全チートシート

シーケンス図は、APIの連携フロー、認証認可シーケンス、マイクロサービス間のメッセージ伝達など、 「誰と誰が、どのような時系列で通信を行うか」 を明快に表現するダイアグラムです。

参加者（participant / actor）の定義と表示名エイリアス

登場するシステムや人物は participant（四角形）または actor（人型アイコン）で宣言します。as キーワードを使用すると、コード内では短い英数字エイリアスを使い、画面上には分かりやすい日本語を表示できます。

```mermaid
sequenceDiagram
    actor U as ユーザー (Client)
    participant F as フロントエンド (SPA)
    participant B as バックエンド (API)
    participant D as データベース (RDB)

    U->>F: 操作ボタンをクリック
    F->>B: APIリクエスト送信
    B->>D: クエリ実行
    D-->>B: 結果レコード返却
    B-->>F: JSONレスポンス返却
    F-->>U: 画面に完了メッセージを表示
```

メッセージ矢印の種類（同期実線 ->>、非同期矢印 -)、点線応答 –>>、バツ印 -x）

UML仕様に則った厳密な矢印表現がサポートされています。線の種類（実線 - / 破線 --）と矢印形状の組み合わせで指定します。

条件分岐（alt / else）、オプション（opt）、ループ（loop）、並行処理（par）

条件分岐や繰り返しなどの制御構造は、ブロック構文でシンプルに表現できます。

• alt ... else ... end： 条件分岐（If-Else）。成功時と失敗時の処理を分割して記述します。
• opt ... end： 任意の処理（Optional）。特定条件下でのみ発生する処理を囲みます。
• loop ... end： 繰り返し処理（Loop）。ポーリング通信やバッチ処理の反復を表現します。
• par ... and ... end： 並列処理（Parallel）。同時に実行される複数の非同期処理を記述します。
• + / -： 矢印末尾に付けてライフライン（処理中を示す縦バー）の活性化と終了を明示します。

実践例：Web API認証・ログインシーケンス

自動番号付け（autonumber）、背景グループ（box）、ノート（Note over）、条件分岐（alt / else）を網羅した実践的なシーケンス図です。

```mermaid
sequenceDiagram
    autonumber
    
    box rgb(240, 248, 255) クライアント環境
    actor User as エンドユーザー
    participant Client as Webブラウザ
    end

    box rgb(245, 245, 250) サーバー環境
    participant Auth as 認証サーバー (Auth0)
    participant API as バックエンドAPI
    participant DB as ユーザーDB
    end

    User->>Client: メールアドレス・パスワードを入力
    Client->>+Auth: POST /oauth/token（認証要求）
    Auth->>DB: 認証情報を検証照会
    DB-->>Auth: ユーザーレコード返却

    alt パスワード一致（認証成功）
        Auth-->>Client: JWTアクセストークン発行 (200 OK)
        Client->>+API: GET /api/v1/profile（Authorization: Bearer トークン）
        API-->>-Client: プロフィールデータ返却
        Client-->>User: マイページ画面を描画表示
    else パスワード不一致（認証失敗）
        Auth-->>-Client: 401 Unauthorized エラー返却
        Note over Client,User: 認証エラーメッセージを表示
        Client-->>User: 「パスワードが正しくありません」を表示
    end
```

【コピペ用】ER図・クラス図・ガントチャート実例集

Mermaidはフローチャートやシーケンス図だけでなく、データベース設計、オブジェクト指向モデリング、プロジェクト管理でも圧倒的な威力を発揮します。

ER図（テーブル定義、PK/FK、1対多などのリレーション記号 ||–o{ ）

データベース設計書で必須となるER図（Entity Relationship Diagram）の書き方です。カーディナリティ（関連性の多重度）は記号の組み合わせで定義します。

```mermaid
erDiagram
    USERS ||--o{ ORDERS : "1対多 (注文履歴)"
    ORDERS ||--|{ ORDER_ITEMS : "1対多 (注文明細)"
    PRODUCTS ||--o{ ORDER_ITEMS : "1対多 (商品明細)"
    CATEGORIES ||--o{ PRODUCTS : "1対多 (商品分類)"

    USERS {
        bigint id PK "ユーザーID"
        string email "メールアドレス (Unique)"
        string password_hash "暗号化パスワード"
        datetime created_at "登録日時"
    }

    ORDERS {
        bigint id PK "注文ID"
        bigint user_id FK "購入者ID"
        int total_amount "注文合計金額"
        string status "ステータス (pending/paid/shipped)"
        datetime ordered_at "注文受付日時"
    }

    ORDER_ITEMS {
        bigint id PK "明細ID"
        bigint order_id FK "注文ID"
        bigint product_id FK "商品ID"
        int quantity "購入数量"
        int unit_price "単価"
    }

    PRODUCTS {
        bigint id PK "商品ID"
        bigint category_id FK "カテゴリID"
        string name "商品名"
        int price "販売価格"
        int stock "在庫数"
    }

    CATEGORIES {
        bigint id PK "カテゴリID"
        string name "カテゴリ名"
        string slug "URLスラッグ"
    }
```

クラス図（属性・メソッド・可視性記号 + – # ~ と継承関係）

ソフトウェア設計書でクラス構造と継承・実装関係を表すクラス図です。メソッドや属性の先頭に可視性記号を付与します。

```mermaid
classDiagram
    class User {
        -String id
        -String email
        #String passwordHash
        +login(password) Boolean
        +logout() void
    }

    class AdminUser {
        -List~String~ permissions
        +banUser(userId) void
        +deletePost(postId) void
    }

    class PaymentProcessor {
        <>
        +charge(amount) Boolean
        +refund(transactionId) Boolean
    }

    class StripeProcessor {
        -String apiKey
        +charge(amount) Boolean
        +refund(transactionId) Boolean
    }

    User <|-- AdminUser : 継承
    PaymentProcessor <|.. StripeProcessor : 実装
```

ガントチャート（タスク日程、依存関係 after、マイルストーン）

プロジェクトのスケジュール表や開発ロードマップをテキストで管理できます。after タスクID で前工程完了後の開始を自動計算し、milestone で重要納期を指定できます。

```mermaid
gantt
    title 新規Webサービス開発スケジュール
    dateFormat YYYY-MM-DD
    axisFormat %m/%d

    section 要件定義・設計
        要件定義策定           :done,    des1, 2026-10-01, 2026-10-10
        DB論理設計・API仕様書   :active,  des2, after des1, 7d
        UI/UXワイヤーフレーム作成:         des3, after des1, 10d

    section バックエンド開発
        認証・認可基盤実装     :crit,    dev1, after des2, 8d
        注文決済API開発        :         dev2, after dev1, 12d

    section フロントエンド開発
        画面モックアップ構築   :         front1, after des3, 10d
        API連携・状態管理実装  :         front2, after dev1, 14d

    section テスト・リリース
        結合テスト・E2E検証    :crit,    test1, after dev2, 7d
        本番環境リリース       :milestone, m1, after test1, 0d
```

マインドマップ（階層構造のブレインダンプ）

新機能のアイデア出しや仕様の洗い出し、サイト構成の設計を階層インデントだけで図式化できます。

```mermaid
mindmap
  root((Markdown学習サイト))
    基礎入門
      見出し記法
      箇条書きリスト
      テーブル表
      リンク・画像
    応用・作図
      Mermaidダイアグラム
        フローチャート
        シーケンス図
        ER図
      数式表現 MathJax
      コードブロック装飾
    エディタ連携
      VS Code
      Notion
      Obsidian
      GitHub
```

主要エディタでのプレビュー環境設定（VS Code / GitHub / Notion / Obsidian）

Mermaidの強みは、主要な開発ツールやノートアプリに標準または拡張機能で完全対応している点です。各ツールのセットアップ手順を解説します。

VS CodeでMermaidをプレビューする拡張機能（Markdown Preview Mermaid Support）

VS Code標準のMarkdownプレビュー機能はMermaid構文に対応していませんが、拡張機能を1つ追加するだけで即座に美しい図がレンダリングされるようになります。より詳しいプレビュー設定や便利なショートカットについては、 VS Code Markdownプレビュー完全ガイド でも詳しく解説しています。

Notion・Obsidianでのネイティブ表示手順（“`mermaidブロック指定）

Notion では特別な拡張機能なしにMermaidを利用できます。ページ上で /mermaid と入力してMermaid専用ブロックを呼び出すか、通常のコードブロック（/code）の言語選択プルダウンから「Mermaid」を指定します。Notionでの詳しいMarkdown活用法については、 Notion Markdown連携ガイド をご覧ください。

Obsidian は、インストール直後からMermaidに 完全ネイティブ対応 しています。ライブプレビューモードにしておけば、コードブロックを書いた瞬間にその場で図が展開されます。内部リンク（[[ノート名]]）と組み合わせたナレッジネットワークの可視化にも最適です。

GitHub README・プルリクエストでの対応状況

GitHubは2022年よりMermaidを 公式標準サポート しています。README.md、Issue、Pull Requestのコメント欄、GitHub Discussionsで ```mermaid と記述するだけで、GitHubのサーバー上でSVG画像として自動レンダリングされます。

PR（プルリクエスト）のレビュー時に、仕様変更に伴う図の修正差分がテキストのGit diffとして行単位で確認できるため、チーム開発でのドキュメント運用効率が劇的に向上します。GitHubにおける詳しい記法ルールは、 GitHub Markdown（GFM）記法ガイド で解説しています。

【エラー解決】Mermaidが表示されない・エラーになる5大原因と対処法

Mermaidでコードを書いていると「Syntax error in text」と赤文字で警告が出たり、図が真っ白になって描画されないトラブルが発生します。初心者が遭遇するエラーの95%以上は、以下の5大原因に当てはまります。

① 日本語テキストをダブルクォーテーション（””）で囲んでいない（最重要）

最も頻出するエラー原因です。ノードの表示名に日本語や、丸括弧 ()、角括弧 []、波括弧 {}、スラッシュ /、コロン : などの記号が含まれていると、Mermaidパーサーが「ノード定義の制御記号」と誤認して構文エラー（Syntax Error）を起こします。

flowchart TD
    A[ユーザー登録(必須入力)] --> B
    %% 丸括弧 () が構文エラーを引き起こす

flowchart TD
    A["ユーザー登録(必須入力)"] --> B
    %% ダブルクォーテーションで囲めば確実に描画

② 全角スペース・全角記号の混入

日本語IME（変換モード）をオンにしたままインデントを入力すると、目に見えない 全角スペース（　） が混入することがあります。また、矢印のハイフンや不等号が全角（ーー＞ や ー＞＞）になっている場合もパースに失敗します。エディタの不可視文字表示機能を有効にし、空白と記号はすべて半角に統一してください。

③ 予約語（end, sub, graph 等）の重複

end、graph、subgraph、style、class などの単語はMermaidの制御構文として予約されています。これらをそのままノードIDに指定するとパーサーが混乱します。

%% ❌ エラーになる例
flowchart TD
    start --> end  %% "end" はsubgraph等の終了予約語のためエラー

%% ⭕ 正しい解決例
flowchart TD
    start(["開始"]) --> finish(["終了"])  %% 別の安全な単語を使う
    %% または
    start --> n_end["終了処理"]

④ Mermaid Live Editorによる構文チェック

エラー箇所が特定できないときは、公式Webツールの 「Mermaid Live Editor（mermaid.live）」 を開いてコードを貼り付けてみましょう。何行目のどの文字で構文エラーが発生しているかがリアルタイムでハイライト表示されます。完成した図をPNGやSVG形式で即座にダウンロードすることも可能です。

⑤ コードブロックの言語指定ミスやバッククォート不足

バッククォートが2つしかなかったり、```mermiad や ```mermaid （末尾に不要なスペース）のように言語指定のスペルミスがあると、通常のテキストコードとして扱われて図がレンダリングされません。必ず先頭と末尾に ``` を配置し、言語名は半角英小文字で mermaid と指定してください。

生成AI（ChatGPT/Claude）にMermaidコードを書かせるおすすめプロンプト

複雑なフローチャートやシーケンス図を一から手書きするのは時間がかかります。ChatGPTやClaudeなどの生成AIに要件メモや仕様書を渡し、Mermaidコードを自動生成させるのが実務における最速のテクニックです。

ただし、そのまま「図を作って」と頼むと、日本語ラベルのダブルクォート抜けや予約語エラーを含む壊れたコードが出力されがちです。以下の 「エラー防止指示入りテンプレートプロンプト」 をそのままコピーして使用してください。

以下の仕様メモをもとに、Markdownで動くMermaidの【フローチャート / シーケンス図】コードを作成してください。

【厳守ルール】
1. コードブロックは ```mermaid 〜 ``` で出力してください。
2. ノードIDは英数字（A, B, Step1, Client等）にし、日本語表示テキストは必ずダブルクォーテーションで囲んでください（例: A["データ検証"]）。
3. 括弧 () や記号を含むラベルも、ダブルクォーテーション内に収めてパースエラーを防いでください。
4. 予約語（end, graph, sub等）を単体でノードIDに使用しないでください。
5. 成功ルートは緑系、エラー・異常ルートは赤系で視覚的に区別できるスタイル定義（classDef）を付与してください。

【仕様・要件メモ】
・処理開始：ユーザーが注文ボタンをクリック
・入力検証：配送先住所とお支払い方法の必須チェック
・在庫確認：商品在庫テーブルを参照（在庫不足ならエラー画面へ）
・決済処理：クレジットカードAPIへ決済リクエスト送信
・決済成功なら注文完了画面を表示しサンクスメール送信
・決済失敗ならエラー理由を表示して再試行を促す

このプロンプトを使用すると、AIが最初から構文エラーの起きない高品質なMermaidコードを出力してくれるため、あとはコピーしてMarkdownに貼り付けるだけで図が完成します。

まとめ＆MermaidチートシートFAQ

Markdown Mermaidを活用することで、専用のドローソフトを立ち上げる必要がなくなり、仕様変更にもテキスト1行の修正で即座に対応できるようになります。Gitでのバージョン管理やプルリクエストでの差分レビューとの親和性も抜群です。

よくある質問（FAQ）