Mermaid 記法入門：Markdown に図を埋め込む 7 種類の図

2026年4月28日約9分

「Markdown は文書には強いが図が描けない」という弱点を補うのが Mermaid です。コードブロックに専用記法を書くだけで、フローチャート・シーケンス図・ガントなどの図を生成できます。GitHub の README、Notion、Obsidian、ChatGPT、Claude といった主要なツールで描画されるため、ドキュメントに図を埋める標準的な手段になっています。

Mermaid とは

Mermaid は JavaScript ベースの図示ライブラリで、テキストから SVG 図を生成します。仕組み：

```mermaid
flowchart LR
    A[開始] --> B{条件}
    B -->|Yes| C[処理]
    B -->|No| D[終了]
```

このコードブロックを Mermaid 対応のレンダラーに通すと、矢印付きのフローチャートが描画されます。

対応している主な環境：

GitHub（README.md / Issue / PR コメント）
GitLab
Notion
Obsidian
VSCode（拡張機能）
ChatGPT、Claude（AI チャットの応答内）
各種ドキュメント生成ツール（Docusaurus、MkDocs、VuePress 等）

サポートされる図の種類

Mermaid で描ける主な図と、それぞれの典型的な用途：

図の種類	キーワード	用途
フローチャート	`flowchart` / `graph`	処理フロー、判断分岐
シーケンス図	`sequenceDiagram`	API 通信、メソッド呼び出し
ガントチャート	`gantt`	プロジェクトスケジュール
クラス図	`classDiagram`	OOP 設計、UML
状態遷移図	`stateDiagram-v2`	UI の状態、ライフサイクル
ER 図	`erDiagram`	データベース設計
円グラフ	`pie`	構成比

1. フローチャート

最も基本かつ頻出。

```mermaid
flowchart TD
    A[ユーザー入力] --> B{バリデーション}
    B -->|OK| C[DB 保存]
    B -->|NG| D[エラー表示]
    C --> E[完了]
    D --> A
```

ポイント：

TD = Top to Down（上から下）、LR = Left to Right（左から右）
ノード形状：[四角]、(角丸)、{ひし形（条件）}、((円))
矢印：--> 通常、-.-> 点線、==> 太線、-->|ラベル| ラベル付き

2. シーケンス図

API のやりとりやメソッド呼び出しの順序を表現。

```mermaid
sequenceDiagram
    Client->>API: POST /login
    API->>DB: SELECT user
    DB-->>API: ユーザー情報
    API-->>Client: JWT トークン
    Client->>API: GET /profile (Bearer JWT)
    API-->>Client: プロフィール
```

ポイント：

->> 同期呼び出し、-->> 戻り値、-) 非同期
参加者は登場順に左から右に並ぶ
Note over A,B: メモ でメモを追加できる

3. ガントチャート

プロジェクトのスケジュール可視化。

```mermaid
gantt
    title プロジェクトのスケジュール
    dateFormat YYYY-MM-DD
    section 設計
    要件定義 :a1, 2026-04-01, 7d
    基本設計 :after a1, 14d
    section 実装
    フロントエンド :2026-04-22, 21d
    バックエンド   :2026-04-22, 28d
    section テスト
    結合テスト :2026-05-20, 7d
```

ポイント：

dateFormat で入力日付の形式を指定
after a1 で他のタスクの後に続けられる
section で区切ってフェーズを表現

4. ER 図

データベースのテーブル間関係を表現。

```mermaid
erDiagram
    USER ||--o{ POST : creates
    POST ||--o{ COMMENT : has
    USER ||--o{ COMMENT : writes
    USER {
        int id PK
        string email
        string name
    }
    POST {
        int id PK
        int user_id FK
        string title
        text body
    }
```

ポイント：

リレーション記法：||--o{ は「1 対多」、||--|| は「1 対 1」
属性に PK（主キー）、FK（外部キー）を付けられる

5. 状態遷移図

UI の状態管理やワークフローを表現。

```mermaid
stateDiagram-v2
    [*] --> 未送信
    未送信 --> 送信中: 送信ボタン
    送信中 --> 成功: 200 OK
    送信中 --> 失敗: エラー
    失敗 --> 未送信: 再試行
    成功 --> [*]
```

ポイント：

[*] は開始・終了状態
状態 --> 状態: イベント でトリガーを書ける

6. クラス図

UML 風のクラス関係。

```mermaid
classDiagram
    class Animal {
        +String name
        +int age
        +eat()
        +sleep()
    }
    class Dog {
        +String breed
        +bark()
    }
    Animal <|-- Dog
```

7. 円グラフ

簡単な構成比表示。

```mermaid
pie title 言語別の利用シェア
    "JavaScript" : 45
    "TypeScript" : 30
    "Python" : 15
    "Go" : 10
```

よくあるハマりどころ

1. レンダラーによる対応バージョン差

Mermaid は活発に開発されており、新機能（stateDiagram-v2 の v2 や C4 図など）はレンダラー側のバージョンに依存します。GitHub は 2025 年時点で比較的新しめ、Notion は古いバージョンに留まることがあります。

2. 日本語の改行・幅問題

ノード内で長い日本語を書くと幅がうまく取れないことがあります。<br/> で明示的に改行するか、短い表現に直すのが現実的：

A[ユーザーが商品を<br/>カートに追加]

3. 矢印ラベルにスペース

矢印ラベルに半角スペースを入れると引用符でくくる必要があります：

A -->|"with space"| B

4. プレビュー前の構文確認

ブラウザの Mermaid Live Editor（mermaid.live）で書いてからコピペすると、構文エラーで GitHub のレンダリングが崩れる事故を防げます。

実用上の選び方：Mermaid vs 他の選択肢

用途	Mermaid	専用ツール
README に簡単な図	✅ Mermaid	drawio (PNG)
細かいレイアウト調整	△ 手間	✅ Figma / drawio
バージョン管理（diff 可能）	✅ Mermaid（テキスト）	❌ バイナリで diff 不可
共同編集	✅ PR 経由	✅ Figma リアルタイム
複雑な UML	△ 複雑になると限界	✅ PlantUML / Lucidchart

「ドキュメント内に図をテキストで残せる」が Mermaid の最大の価値で、Git にコミットして diff を残せる点が他形式に対する優位です。

まとめ

Mermaid は Markdown に図をテキストで埋め込める
フローチャート、シーケンス、ガント、ER、状態、クラス、円グラフに対応
GitHub・Notion・Obsidian・主要 AI チャットでネイティブ描画
バージョン管理で図を扱える

Markdown 文書を書きながら Mermaid 図のプレビューを確認したい場合、本サイトの Markdown プレビューツールで簡易的に試せます（Mermaid 描画は環境依存なので、最終的な見え方は配信先の GitHub / Notion 等での確認推奨）。