【コピペで使える】Markdown Mermaid記法の書き方完全ガイド｜フローチャート・シーケンス図・ガントチャート作成入門

Markdown（マークダウン）でシステム設計書、仕様書、APIドキュメント、プロジェクトのREADME、技術ブログを書いていると、「文章だけでなく、処理の流れやシステム構成、スケジュールをきれいな図（ダイアグラム）で分かりやすく伝えたい」という場面が頻繁にあります。

しかし、一般的な作図ツールやデザインソフト（PowerPoint、Figma、draw.ioなど）で作図した画像を貼り付けると、「少し仕様変更があるたびにツールを開いて画像を書き出し、再アップロードする手間がかかる」「Gitで差分（バージョン管理）を追跡できない」といった大きな課題が生じます。

そんな悩みを一挙に解決するのが、テキスト（Markdown）だけで図やグラフを描画できるJavaScriptベースのダイアグラム作成ツール「Mermaid（マーメイド）」です。

Markdown文書の中に ```mermaid とコードを書くだけで、GitHub、Notion、Obsidian、VS Code、Qiita、Zennなどの主要環境で自動的に美しいフローチャートやシーケンス図、ガントチャート、ER図がレンダリングされます。

この記事では、「Mermaid記法（mermaid 記法 / markdown mermaid）」の基本構文から、コピペですぐに使える図表テンプレート集（フローチャート・シーケンス図・ガントチャート・クラス図・ER図）、主要エディタでのプレビュー方法、「図が表示されない・エラーになる時の対処法」まで、初心者にもわかりやすく徹底解説します！

【早見表】Mermaidで作成できる主な図とMarkdownコード一覧

Mermaidでは、1行目の「図タイプ宣言」を変えるだけで多種多様なダイアグラムを描画できます。まずはどのような図が作れるのか、代表的な図表と構文の概要を早見表で確認しましょう。

Mermaidとは？Markdownで図やチャートを描く基本の書き方

Mermaid（マーメイド）は、Markdownテキストのようなシンプルな構文でダイアグラムやチャートを生成できるオープンソースのJavaScriptライブラリです。2014年にSvein Ove Aas氏によって開発がスタートし、現在ではGitHubの公式Markdownレンダラーにも標準採用されるなど、エンジニア・テクニカルライターの業界標準ツールとして広く普及しています。

なぜMarkdown×Mermaidが選ばれるのか？（3大メリット）

従来の画像ファイル（PNGやJPEG）による作図と比較して、Markdown内でMermaid記法（mermaid markdown）を使うことには以下のような圧倒的なメリットがあります。

基本構文：“`mermaid ブロックの書き方

Markdown内でMermaid図を記述するルールはとてもシンプルです。通常の Markdownコードブロック記法 と同様に、バッククォート3つ（```）に続けて言語名として mermaid と指定します。

```mermaid
[ここにMermaid構文を記述]
```

```mermaid
flowchart LR
    A[開始] --> B[処理実行]
    B --> C[完了]
```

Mermaidの基本ルール（図タイプ宣言・インデント・コメント）

Mermaidコードを書く際は、以下の3つの基本ルールを押さえておくとスムーズです。

• 1. 1行目に図タイプを宣言する： flowchart TD や sequenceDiagram など、どの種類の図を描くかを必ず最初に明記します。
• 2. インデントで構造を見やすくする： 構文上はスペースやインデントは厳密に強制されませんが、半角スペース2〜4個でインデントすると構造が把握しやすくなります。
• 3. コメント行の書き方（%%）： 行頭に %%（パーセント記号2つ）を付けると、その行はコメントとなりレンダリング時に無視されます。

```mermaid
flowchart TD
    %% これはコメントです（画面には描画されません）
    Node1[ノード1] --> Node2[ノード2]
```

【コピペで使える】フローチャート（処理フロー・分岐図）の書き方

Mermaidで最もよく使われるのが「フローチャート（flowchart）」です。業務プロセスの可視化、プログラムのロジック、アルゴリズムの分岐などを直感的に表現できます。

※以前は graph というキーワードも使われていましたが、現在ではより高機能な flowchart を使用することが公式で推奨されています。

1. グラフの方向指定（TD / LR / BT / RL）

flowchart の直後にアルファベット2文字を指定することで、図が伸びる方向（上から下、左から右など）をコントロールします。

2. ノードの形状一覧（四角・丸・ひし形・DB等）

ノード（箱）を囲む括弧の種類を変えるだけで、さまざまな形の図形を表現できます。ノードIDの後ろに対応する括弧を記述します。

3. 矢印と線の種類（実線・破線・太線・ラベル付き）

ノード同士をつなぐ線や矢印にも多様なバリエーションが用意されています。

```mermaid
flowchart LR
    A1[実線矢印] --> B1[ノード]
    A2[ラベル付き矢印] -->|条件テキスト| B2[ノード]
    A3[破線・点線] -.-> B3[ノード]
    A4[ラベル付き破線] -.->|注釈| B4[ノード]
    A5[太線矢印] ==> B5[ノード]
    A6[ラベル付き太線] ==>|重要ルート| B6[ノード]
    A7[矢印なし実線] --- B7[ノード]
    A8[双方向矢印] <--> B8[ノード]
```

4. 条件分岐を含む実践フローチャート例（ユーザーログイン処理）

ノード形状、矢印ラベル、条件分岐を組み合わせた実践的なログイン処理フローチャートです。コピペしてそのまま利用できます。

```mermaid
flowchart TD
    Start([ユーザーがログイン画面にアクセス]) --> Input[/ID・パスワードを入力/]
    Input --> Check{入力内容の検証}
    
    Check -->|OK| AuthDB[(認証DBへ照会)]
    Check -->|未入力・形式不正| Error1[エラーメッセージ表示]
    Error1 --> Input
    
    AuthDB --> AuthResult{一致するか？}
    AuthResult -->|一致（成功）| IssueToken[JWTトークン発行 / セッション確立]
    IssueToken --> Dashboard[マイページ・ダッシュボードへ遷移]
    Dashboard --> Finish([ログイン完了])
    
    AuthResult -->|不一致（失敗）| RetryCount{失敗回数チェック}
    RetryCount -->|3回未満| Error2[パスワード不一致警告]
    Error2 --> Input
    RetryCount -->|3回以上| LockAccount[アカウント一時ロック]
    LockAccount --> FinishFail([ロック画面表示])
```

5. サブグラフ（subgraph）でシステムや処理単位をグループ化する

システム構成やマイクロサービス設計など、複数のノードを「フロントエンド」「バックエンド」「データベース」のように枠で囲んでまとめたい場合は subgraph 構文を使用します。

```mermaid
flowchart TB
    subgraph Client["クライアント環境（ブラウザ / アプリ）"]
        UI[Reactフロントエンド]
    end

    subgraph Server["バックエンドAPIサーバー"]
        API[Node.js / Express API]
        AuthService[認証マイクロサービス]
    end

    subgraph Storage["データ永続化層"]
        DB[(PostgreSQL)]
        Cache[(Redisキャッシュ)]
    end

    UI -->|HTTPSリクエスト| API
    API -->|認証確認| AuthService
    API -->|SQLクエリ| DB
    API -->|高速読み取り| Cache
```

6. ノードの色やスタイルをカスタマイズする（style / classDef）

特定のノードを目立たせたい場合や、エラーノードを赤色、成功ノードを緑色に塗りたい場合は、CSSライクなスタイル指定が可能です。

```mermaid
flowchart LR
    A[通常ノード] --> B[成功ノード]
    A --> C[警告・エラーノード]

    %% 個別スタイル指定（ノードIDに対して指定）
    style B fill:#d4edda,stroke:#28a745,stroke-width:2px,color:#155724
    style C fill:#f8d7da,stroke:#dc3545,stroke-width:2px,color:#721c24
```

【コピペで使える】シーケンス図（時系列・システム間通信）の書き方

APIの通信シーケンス、マイクロサービス間のメッセージやり取り、ユーザー認証フローなど、「誰と誰が、どのような順番でメッセージをやり取りするか（時系列）」を表現するのに最適なのが「シーケンス図（sequenceDiagram）」です。

1. 参加者（participant / actor）の定義とエイリアス

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

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

    U->>F: ボタンをクリック
    F->>B: GET /api/users
    B->>D: SELECTクエリ発行
    D-->>B: ユーザーデータ返却
    B-->>F: JSONレスポンス (200 OK)
    F-->>U: 画面に一覧を描画
```

2. メッセージ矢印の種類（同期・非同期・点線応答）

シーケンス図のメッセージ矢印は、線の種類（実線 - / 破線 --）と矢印の形状（塗りつぶし >> / 開き矢印 > / 矢印なし）の組み合わせで指定します。

3. 処理ブロック（ライフラインのアクティブ化：activate / deactivate）

サーバーが処理を行っている期間を視覚的に表す長方形（アクティベーションバー）を表示するには、activate ノード名 と deactivate ノード名 を記述します。矢印の末尾に +（開始）や -（終了）を付ける短縮記法も便利です。

```mermaid
sequenceDiagram
    participant C as クライアント
    participant S as サーバー

    C->>+S: データ処理リクエスト（処理開始）
    Note over S: データベース集計中...
    S-->>-C: 処理完了レスポンス（処理終了）
```

4. 条件分岐（alt / else）、オプション（opt）、ループ（loop）

処理の分岐や繰り返しは、枠で囲む制御構文で簡単に表現できます。

• alt ... else ... end： 条件分岐（if-else）。成功時とエラー時の処理分岐に利用
• opt ... end： 任意の処理（Optional）。特定の条件でのみ実行する処理
• loop ... end： 繰り返し処理（for / while / ポーリング通信など）
• par ... and ... end： 並列処理（Parallel）。同時に実行される複数の非同期処理

5. 実践例：OAuth 2.0認証フローのシーケンス図

条件分岐（alt）、ノート（Note）、背景グループ（box）を網羅した実践的な認証フローのシーケンス図です。

```mermaid
sequenceDiagram
    autonumber %% メッセージに自動で通し番号（1, 2, 3...）を付与
    
    box rgb(245, 247, 250) クライアントサイド
    actor User as ユーザー
    participant Browser as Webブラウザ
    end
    
    box rgb(240, 249, 255) サーバーサイド
    participant AppServer as 自社Webサーバー
    participant AuthServer as OAuth認証プロバイダ (Google/GitHub等)
    end

    User->>Browser: 「外部アカウントでログイン」をクリック
    Browser->>AppServer: ログインリクエスト
    AppServer-->>Browser: 認証プロバイダの認可URLへリダイレクト (302)
    Browser->>AuthServer: 認可画面を要求
    AuthServer-->>Browser: ログイン＆同意画面を表示
    
    User->>AuthServer: ID・パスワード入力＆アクセス許可
    AuthServer-->>Browser: 認可コード付きでコールバックURLへリダイレクト
    Browser->>AppServer: 認可コードを送信
    
    AppServer->>+AuthServer: 認可コード＋クライアントシークレットを送信 (POST /token)
    
    alt 認証成功の場合
        AuthServer-->>AppServer: アクセストークン & ユーザー情報を返却 (200 OK)
        AppServer->>AppServer: ユーザーセッション作成
        AppServer-->>Browser: ログイン成功・マイページへリダイレクト
        Browser-->>User: マイページ画面を表示
    else 認証失敗（不正なコードまたは期限切れ）
        AuthServer-->>-AppServer: エラーレスポンス (400 Bad Request)
        AppServer-->>Browser: ログイン失敗画面へリダイレクト
        Browser-->>User: エラーメッセージを表示
    end
```

【コピペで使える】その他人気図表テンプレート集（ガントチャート・クラス図・ER図）

Mermaidはフローチャートやシーケンス図だけでなく、スケジュール管理、データベース設計、オブジェクト指向設計、データ可視化など幅広い図表に対応しています。

1. ガントチャート（gantt：プロジェクト進捗・スケジュール管理）

プロジェクトのスケジュールやタスク日程を直感的に可視化できます。crit（クリティカルパス）、done（完了済み）、active（進行中）、after タスク名（依存関係指定）などの属性を指定できます。

```mermaid
gantt
    title Webサイトリニューアル プロジェクト計画
    dateFormat YYYY-MM-DD
    axisFormat %m/%d
    
    section 要件定義・設計
    要件ヒアリング       :done,    des1, 2026-09-01, 2026-09-07
    ワイヤーフレーム作成 :done,    des2, after des1, 5d
    UIデザイン設計       :active,  des3, after des2, 7d
    
    section 開発フェーズ
    フロントエンド実装   :crit, active, dev1, after des3, 10d
    バックエンドAPI開発  :crit,         dev2, after des3, 12d
    データベース移行     :              dev3, after dev2, 4d
    
    section テスト・リリース
    結合テスト・QA検証   :test1, after dev1, 7d
    本番環境デプロイ     :milestone, release, after test1, 0d
```

2. クラス図（classDiagram：オブジェクト指向設計）

クラスのプロパティ（属性）、メソッド（関数）、可視性（+ public, - private, # protected）、継承関係（|--）を定義できます。

```mermaid
classDiagram
    class User {
        +int id
        +string name
        -string passwordHash
        +login(password) bool
        +logout() void
    }

    class AdminUser {
        +string role
        +deleteUser(userId) bool
    }

    class Post {
        +int id
        +string title
        +string content
        +publish() void
    }

    User <|-- AdminUser : 継承
    User "1" --> "*" Post : 投稿を作成
```

3. ER図（erDiagram：データベース設計・テーブルリレーション）

データベースのテーブル定義と外部キー連携を表現できます。リレーション記号（||--o{ など）で「1対1」「1対多」「多対多」を明確に示せます。

```mermaid
erDiagram
    USERS ||--o{ ORDERS : "1人のユーザーは複数の注文を持つ"
    ORDERS ||--|{ ORDER_ITEMS : "1つの注文は1つ以上の商品明細を持つ"
    PRODUCTS ||--o{ ORDER_ITEMS : "1つの商品は複数の明細に含まれる"

    USERS {
        int id PK "ユーザーID"
        string email "メールアドレス"
        string name "氏名"
        datetime created_at "登録日時"
    }

    ORDERS {
        int id PK "注文ID"
        int user_id FK "ユーザーID"
        datetime order_date "注文日時"
        int total_amount "合計金額"
    }

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

    PRODUCTS {
        int id PK "商品ID"
        string name "商品名"
        int price "価格"
        int stock "在庫数"
    }
```

4. 状態遷移図（stateDiagram-v2：ステータス管理）

開始状態（[*]）、通常状態、終了状態を矢印で結び、ステータス変更の条件やイベントを定義します。

```mermaid
stateDiagram-v2
    [*] --> 下書き : 新規作成
    下書き --> レビュー待ち : 申請提出
    レビュー待ち --> 下書き : 差し戻し
    レビュー待ち --> 公開中 : 承認・公開
    公開中 --> アーカイブ : 非公開化
    アーカイブ --> [*] : 削除完了
```

5. 円グラフ（pie：データ比率の可視化）

シンプルなデータ集計やアンケート結果を円グラフとしてMarkdown内に手軽に埋め込めます。

```mermaid
pie title チーム内で使われているMarkdownエディタ割合
    "VS Code" : 48
    "Obsidian" : 26
    "Notion" : 16
    "その他エディタ" : 10
```

各ツール・エディタでのMermaid対応状況とプレビュー設定

Mermaidの大きな魅力は、多くの開発ツールやノートアプリが標準または簡単な拡張機能の追加だけでサポートしている点です。主要な環境での設定方法とプレビュー手順をまとめました。

1. GitHub（Issue / Pull Request / README / Discussions）

設定不要・完全標準対応です。GitHub上の README.md、Issue、Pull Requestのコメント、Discussionsなどに ```mermaid ブロックを書くだけで、GitHubが自動的にSVG画像としてレンダリングしてくれます。

2. VS Code（Visual Studio Code）

VS Code の標準Markdownプレビュー機能（Ctrl + Shift + V または Cmd + Shift + V）でMermaidを表示させるには、無料の公式・定番拡張機能を1つ導入するのが最もおすすめです。

3. Obsidian

ナレッジ管理ツール「Obsidian」は、初期状態からMermaidにネイティブ対応しています。ライブプレビューモードでコードを書いた瞬間からリアルタイムに図がレンダリングされ、内部リンク（[[ノート名]]）と組み合わせたナレッジネットワーク構築にも威力を発揮します。

4. Notion

Notion では、スラッシュコマンド /mermaid と入力するか、通常のコードブロックを配置して言語選択を「Mermaid」に設定することで、即座に図表プレビューとコード編集の切り替え表示が可能です。

主要プラットフォーム対応比較まとめ一覧表

Mermaidで図が表示されない・エラーになるときの原因と解決法

Mermaidのコードを書いていて「Syntax error in text」と表示されたり、図が真っ白になってレンダリングされない場合、以下の5つのポイントを順にチェックしてください。

① 特殊文字（括弧・コロン・引用符）をダブルクォートで囲んでいない

ノードの表示名の中に、丸括弧 ()、角括弧 []、波括弧 {}、コロン :、不等号 <> などの記号を含めると、Mermaidパーサーが「構文記号」と誤認してエラーになります。

flowchart TD
    A[ユーザー登録(必須入力)] --> B
    %% 括弧 () が構文と衝突してエラー

flowchart TD
    A["ユーザー登録(必須入力)"] --> B
    %% ダブルクォートで囲めば安全に描画

② 全角スペースや全角記号が混入している

インデントや矢印の周辺に全角スペース（　）や全角ハイフン（ー）、全角矢印（＞）が混ざっていると、構文エラーが発生します。エディタの空白文字可視化機能を有効にして、すべて半角文字に統一してください。

③ 予約語（end, sub, graph 等）をノードIDに使っている

end、graph、subgraph、style、call、click などのMermaid制御用キーワードをそのままノードの変数名（ノードID）として使用するとパーサーが混乱します。node_end[終了] や E1[end] のように別の識別子を割り当ててください。

④ 最速デバッグ方法：Mermaid Live Editorを活用する

エラーの原因がどうしても分からない場合は、公式が提供している無料のブラウザツール「Mermaid Live Editor（mermaid.live）」にコードを貼り付けてみましょう。何行目のどの文字で文法エラーが発生しているかがリアルタイムで赤字表示されるため、一瞬で修正箇所を特定できます。

Markdown Mermaidに関するよくある質問（FAQ）

まとめ：Markdown Mermaidを活用してドキュメント作成を効率化しよう

この記事では、Markdown内でダイアグラムを描けるMermaid記法（mermaid 記法 / markdown mermaid）の基本構文、フローチャートやシーケンス図、ガントチャートの実践テンプレート、エディタ環境、トラブルシューティングまで網羅して解説しました。

Mermaidを取り入れることで、「仕様変更に強く、Gitでレビューしやすく、誰でも手軽にメンテナンスできるドキュメント」が簡単に実現できます。

まずはこの記事のテンプレートをコピーして、GitHubのREADMEやVS Code、Notionで動かしてみてください。テキストだけで直感的に図が描ける快適さを実感できるはずです！