MENU

マーメイド記法(Mermaid)

1. マーメイド記法とは何か？

1.1 概要

Mermaid (マーメイド) は、テキストベースの記法により フローチャート、シーケンス図、ガントチャート、クラス図、ER 図(エンティティ関係図)、状態遷移図、ユーザージャーニーマップ など、さまざまな ダイアグラム(図) を 簡単かつ可読性の高い 形で作成できるオープンソースのライブラリです。
マークダウンに直接埋め込むことができ、GitHub などのプラットフォームでも一部サポートが進んでいます。UML 図作成にも重宝されるほどの柔軟性と可読性が特徴で、ソフトウェア開発のドキュメントや要件定義、システム構成図など幅広い領域で活用されています。

1.2 誕生の背景

もともと、GitHub Flavored Markdown (GFM) などで流れ図やシーケンス図を描くには、ASCIIアートや外部ツールの画像を貼り付けるなど不便が多々ありました。
しかし、テキストベースで図を管理できると、バージョン管理がしやすく、修正履歴も追いやすい。そこで登場したのが Mermaid です。
Mermaid は図を「テキスト」そのものとして書くことにより、差分管理・コラボレーションが容易になります。

1.3 Mermaid の代表的なメリット

  1. バージョン管理に優れている
    • テキストとしてGitリポジトリで管理できる。
    • 差分も容易に確認可能。
  2. 学習コストが低い
    • 記述は直感的な英語ベースのシンプルな構文。
    • 言語的にも自然なので覚えやすい。
  3. 様々な形式のダイアグラムをサポート
    • フローチャート、シーケンス図、ガントチャート、ER 図など、幅広く対応。
    • 特定の UML 記法に限らず柔軟に利用できる。
  4. 様々な場所でレンダリング可能
    • Web ブラウザ、VSCode 拡張機能、GitLab / GitHub Pages / Notion / Confluence などで利用可能。
    • 独自にローカルで CLI ツールを使ってレンダリングすることも可能。

2. Mermaid の基本書式

Mermaid のコードは主に、下記のような 「3 つのバッククォート + mermaid」 で始まり、その後にダイアグラムの種類やオプションが続きます。

<ダイアグラムの種類> <オプション(必要なら)>
    <記法に沿った定義>

例えば、フローチャートを記述するときは flowchart、シーケンス図を記述するときは sequenceDiagram というキーワードを使います。

以下に、最も基本的なフローチャートの例を示します。

flowchart LR
    A[スタート] --> B{条件分岐1?}
    B -->|Yes| C[処理A]
    B -->|No| D[処理B]
    C --> E[処理結果A]
    D --> E[処理結果B]
    E --> F[終了]
  • flowchart LR の部分がダイアグラムの種類と方向を表す指定です。
    • LR は Left to Right(左から右) を意味し、フローチャートを左から右に描画します。
    • その他に TB (Top to Bottom)、RL (Right to Left)、BT (Bottom to Top) などの選択肢があります。

3. フローチャート (Flowchart) 詳説

3.1 基本構文

フローチャートを記述する際は、flowchart <方向> を先頭に書き、矢印でノードをつないでいきます。ノード同士は --> や --- の表記で結び、分岐や条件を {} で表現します。

例:

flowchart TB
    A[開始] --> B{条件X?}
    B -->|はい| C[分岐1]
    B -->|いいえ| D[分岐2]
    C --> E[処理C]
    D --> E[処理D]
    E --> F[終了]

3.1.1 ノードのラベル付け

  • [ ] (角括弧)は長方形のノード
  • ( ) (丸括弧)は円弧形状のノード
  • { } (波括弧)はひし形ノード
  • (( )) (丸括弧を2重)は円形ノード（開始・終了ノードなどで使いやすい）

ラベルは [ ] 内などに記述します。
例: A[スタート] と書くと、ノードAに「スタート」と表示される長方形を描画します。

3.1.2 ノードID と表示ラベル

ノードの ID は図中で一意に管理されるための識別子、角括弧 [ ] 内などに表示するテキストはユーザー向けのラベルです。
Mermaid ではノードID とラベルを同じように表記できますが、同じ ID を複数個所に使うと衝突しないよう注意が必要です。

flowchart LR
    A(開始) --> B{条件?}
    B -->|Yes| C(処理C)
    B -->|No|  D(処理D)

3.2 矢印・線の表現

  • 通常の矢印: --> (実線)
  • 太線: ==> (二重線)
  • 点線: -.->
  • テキスト付きの分岐: -->|Yes|

3.3 特殊構文: サブグラフ(subgraph)

大きな図の一部をまとめたいときに便利なのが subgraph 構文です。サブグラフを使うと、フローチャートの中にまとまりを作り、見通しを良くすることが可能です。

flowchart TB
    A[開始] --> B{条件A?}
    
    subgraph グループ1
    B --> C[処理1]
    C --> D[処理2]
    end
    
    D --> E[別の処理]
    E --> F[終了]
  • subgraph [名前] と end の間にサブグラフに含めたいノード定義を入れる。
  • サブグラフにも subgraph id [名前] と ID を付けることができ、カスタマイズが可能。

3.4 ノードやエッジのクラス指定・カスタムスタイル

flowchart LR
    classDef critical fill:#ff9999, stroke:#ff0000, stroke-width:2px
    
    A([スタート]) --> B((判定A))
    B --> C[処理C]
    B --> D[処理D]

    class C,D critical
  • classDef <className> <CSSプロパティ> でクラスの見た目を定義。
  • class <ノードリスト> <className> で一度に複数ノードにクラスを付与できる。

これを使えば、フローチャートの特定ノードをハイライトしたり、色や枠線をカスタムしたりが可能です。

4. シーケンス図 (Sequence Diagram) 詳説

4.1 基本書式

シーケンス図の記述には sequenceDiagram を使います。たとえば以下のような例があります:

sequenceDiagram
    participant Alice
    participant Bob
    
    Alice->>Bob: こんにちは
    Bob->>Alice: やあ、元気？
    Alice-->>Bob: とても元気です

4.1.1 登場人物の定義

  • participant <名前> でシーケンス図に登場するオブジェクト (人物やシステム) を定義します。
  • Alice->>Bob: メッセージ の形式で、Alice が Bob に向けてメッセージを送るフローを定義します。

4.1.2 メッセージの種類

  • ->> はメッセージ送信を意味します(実線の矢印)。
  • -->> は点線の矢印。
  • ->> と -->> で同期/非同期を表す表現方法として使うことが多いです。

4.1.3 アクティベーション(実行領域)やノート、オプションなど

Mermaid のシーケンス図では、その他に以下のような構文が利用可能です。

  • activate <participant> / deactivate <participant>
    実行領域(アクティベーションバー)を示す。
  • Note over <participant> / Note left of <participant> / Note right of <participant>
    メモ(ノート)を追加する。 sequenceDiagram participant Alice participant Bob Note left of Alice: Alice のメモ Alice->>Bob: こんにちは Note over Bob: Bob のメモ
  • alt / opt / par / loop / critical などのブロック構文
    • alt <条件>: 条件分岐
    • opt: オプションフロー
    • par: 並行処理
    • loop: 繰り返し
    • critical: クリティカル(エラー処理など)

例: alt (条件分岐) の例

sequenceDiagram
    participant A
    participant B

    A->>B: データ要求
    alt データあり
        B->>A: データ返信
    else データなし
        B->>A: エラー通知
    end

5. ガントチャート (Gantt Chart) 詳説

5.1 ガントチャートとは

プロジェクト管理やスケジュール管理に使われる代表的なツールがガントチャートです。Mermaid でもシンプルな構文でガントチャートを作成できます。

5.2 基本構文

gantt
    dateFormat YYYY-MM-DD
    title プロジェクト進行計画

    section 準備フェーズ
    要件定義       :task1, 2025-01-01, 7d
    環境構築       :task2, after task1, 5d

    section 実装フェーズ
    開発           :task3, 2025-01-14, 10d
    テスト         :task4, after task3, 7d
  • gantt で始める。
  • dateFormat で日付の形式を指定。
  • title でガントチャート全体のタイトルを表示。
  • section でセクション(フェーズ)を分ける。
  • タスクの指定形式: <タスク名> :<タスクID>, <開始日>, <日数> または、 <タスク名> :<タスクID>, after <別タスクID>, <日数> のように指定すると、自動的に前のタスク終了後からのスケジュールが組まれる。

5.2.1 タスクバーの色・カスタマイズ

gantt
    dateFormat YYYY-MM-DD
    title サンプルガント

    section 開発前
    要件定義 :a1, 2025-01-01, 3d
    style a1 fill:#f96,stroke:#333,stroke-width:1px
  • style <タスクID> fill:<色>, stroke:<枠線色>, stroke-width:<太さ> のように、個々のタスクバーの色を変更できる。

6. クラス図 (Class Diagram) 詳説

6.1 基本構文

classDiagram
    class クラスA {
        +属性1: int
        -属性2: string
        +メソッドA(param1: int): void
    }

    クラスA <|-- クラスB
    クラスA o-- クラスC
  • classDiagram でクラス図を宣言。
  • クラスA <|-- クラスB は継承(一般的に「B extends A」を表す)。
    記号には <|-- (継承) のほかに、 *-- (コンポジション) や o-- (アグリゲーション) など、UML の表記を反映したものを利用可能。
  • クラス内部のメンバーの可視性を示すとき、+ は public、- は private、# は protected、 ~ は package-private を意味する。

6.1.1 関係のバリエーション

  • 継承: <|-- (左側が親、右側が子)
  • 実装 (インターフェース): <|..
  • 依存: ..>
  • 関連: --
  • アグリゲーション: o--
  • コンポジション: *--

6.2 クラス同士の依存・関連

classDiagram
    class Controller
    class Service
    class Repository

    Controller ..> Service : uses
    Service ..> Repository : depends on
  • Controller ..> Service は「Controller が Service を利用する依存関係」を示す。

7. ER 図 (Entity Relationship Diagram) 詳説

7.1 基本構文

ER 図(エンティティ関係図)は、データベースのテーブルやカラム間の関連を表すのに使います。Mermaid で ER 図を描く場合は、次のように erDiagram と宣言します。

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    CUSTOMER {
        string name
        string address
        int    customer_id PK
    }
    ORDER {
        int order_id PK
        string date
    }
    LINE-ITEM {
        int line_item_id PK
        int quantity
        float price
    }
  • ||--o{ などの記号でリレーションの種類(1対多、多対多など)を表す。
    • ||: 1
    • |{: 多
    • o{: 0 以上 (可変)
  • { } 内でカラムを定義し、PK や FK などの修飾子を付けられる。

7.1.1 リレーションの書き方

  • A ||--|| B : "リレーション名" : 一対一
  • A ||--|{ B : "リレーション名" : 一対多
  • A }|--|{ B : "リレーション名" : 多対多
  • o は 0個以上を示す可変マーク

8. 状態遷移図 (State Diagram) 詳説

8.1 基本書式

状態遷移図（ステートマシン）を表現するには stateDiagram または stateDiagram-v2 を使います。
たとえば以下のように定義できます。

stateDiagram
    [*] --> State1
    State1 --> State2: イベントA
    State2 --> State3: イベントB
    State3 --> [*]
  • [*] は開始状態や終了状態を表す記法。
  • State1 --> State2: イベント のように、状態遷移を記述する。

8.2 コンポジットステート(入れ子状態)

状態遷移図には、状態の中にさらにサブ状態を定義できる場合があります。

stateDiagram
    [*] --> Idle
    Idle --> Active: start
    state Active {
        [*] --> SubState1
        SubState1 --> SubState2: move
        SubState2 --> [*]
    }
    Active --> Idle: stop
  • state <状態名> { ... } でサブステートを定義。

9. ユーザージャーニーマップ (User Journey) 詳説

9.1 基本構文

ユーザの行動や感情の流れを可視化するのがユーザージャーニーマップです。Mermaid では journey というキーワードで簡単なジャーニーマップを表現可能です。

journey
    title ユーザーの1日の流れ
    section 朝
      ユーザーがログイン: 5: とても簡単
      ホーム画面を確認: 3: 少しストレス
    section 昼
      商品を検索: 4: 概ね快適
      商品を購入: 2: ややストレス
  • title で全体のタイトル。
  • section で区切り。
  • 各行で、<アクション>: <評価(数値)>: <コメント> という書式で指定。評価(数値)は1～5などで記述することが多い。

10. Mermaid を活用する際の実践ポイント

10.1 Markdown との連携

多くの場合、Markdown ファイル内に次のように書きます:

“`mermaid flowchart LR … “`

ただし、GitHub では 2023 年現在、Mermaid が 公式サポート されており、.md ファイル内で上記のように書くと、そのままプレビューでレンダリングされる場合があります。
GitLab, Bitbucket, Confluence, Typora, Obsidian, Visual Studio Code (拡張機能) なども対応が進んでおり、プラットフォームによっては別途プラグインを入れることで簡単にプレビューできます。

10.2 Visual Studio Code の拡張機能

  • “Markdown Preview Mermaid Support” などをインストールすると、VSCode 上でマークダウンプレビューを確認できます。
  • Mermaid 専用のエディタ拡張 (Syntax highlight) や、リアルタイムプレビューを実現するものも多く存在。

10.3 CLI ツールを使ったビルドプロセス

Mermaid には mermaid-cli というコマンドラインツールが存在し、以下のように .mmd ファイルを指定して SVG や PNG などに一括出力できます。

npx @mermaid-js/mermaid-cli -i input.mmd -o output.svg

このように自動ビルドパイプラインに組み込むことで、最新版のダイアグラムを常に画像として出力できます。

10.4 Mermaid の設定・テーマ

Mermaid では、デフォルトのテーマ以外にダークテーマやカスタムテーマを設定できます。
設定例:

{
  "theme": "forest"
}

その他にも dark / neutral などのテーマが用意されているほか、CSS で細かくカスタマイズ可能です。

11. バージョン管理・コラボレーション上のメリット

  1. レビューがしやすい
    • Mermaid コード自体がテキストなので、Pull Request 上でフローチャートやシーケンス図の変更点を一目で把握できる。
  2. 再利用が簡単
    • 特定の業務フロー図などをテンプレート化し、コピペで使い回せる。
  3. ドキュメント生成との連動
    • 自動生成スクリプトで .mmd ファイルから PDF / HTML / PNG をビルドしてドキュメントを作成できる。

12. よくあるトラブルシューティング

  1. GitHub で Mermaid が表示されない
    • まだ対応前の GFM (古いバージョン) か、何らかの理由で mermaid ブロックが認識されていない可能性。
    • レンダリングされる環境をチェックし、対応していない場合は mermaid-cli や外部サービスで画像化して貼り付ける。
  2. ノードや関係線の誤字
    • Mermaid では ID にスペースが含められなかったり、大文字小文字を間違えると図が一部レンダリングされない。
    • --- と --> を混同すると、意図しない図になる可能性がある。
  3. 大規模図の見づらさ
    • ノード数が多いとデフォルトのレイアウトだと煩雑になる。
    • サブグラフを活用したり、図を複数に分割して可読性を向上させる工夫が必要。
  4. ブラウザやビルド環境による差異
    • Mermaid.js のバージョンによって、一部の構文が使えない / バグがある場合がある。
    • 常に最新の Mermaid (公式 GitHub リポジトリ) のドキュメントを確認すると良い。

13. 高度な活用テクニック

13.1 自由な CSS カスタマイズ

Mermaid では、各ダイアグラム要素に対して class を付与し、独自の CSS をあてがうことが可能です。
これにより、ブランドカラーに合わせたカラースキームや、図形の大きさ・余白を細かく調整できます。

13.2 Interactive Mermaid

ブラウザ上で Mermaid を動的に扱う場合、JavaScript で Mermaid の API を呼び出して、動的にダイアグラムを差し替え・再描画することもできます。
例: mermaidAPI.initialize(options); mermaidAPI.render('id', mermaidSource, callback);

13.3 ASCII アートの代替

かつての手打ち ASCII アートを使わずに済むので、特にシーケンス図や複雑なフローチャートなどをテキストで整形する必要がなくなります。
Mermaid は可読性とメンテナンス性を大きく向上させてくれます。

14. まとめ

ここまで、マーメイド記法(Mermaid)を 1000倍詳しく、さまざまな観点から丁寧に説明してきました。ポイントを振り返ると:

  1. Mermaid は多種多様なダイアグラムをテキストベースで記述できるオープンソースライブラリ。
  2. 簡潔・直感的な記法 でありながら、フローチャート、シーケンス図、ガントチャート、クラス図、ER 図、状態遷移図、ユーザージャーニーマップ など、幅広い用途に対応。
  3. バージョン管理やコラボレーション に適した形式で、Pull Request 等でのドキュメント更新の差分比較が容易。
  4. GitHub, GitLab, VSCode, Notion, Confluence など、 多くのプラットフォームでサポートが進行中 で使い勝手が良い。
  5. mermaid-cli や CSS でカスタムすれば、自動ビルドパイプライン への組み込みや テーマカスタマイズ も可能。

従来、図を更新するたびに画像編集ツールを立ち上げて修正し、再度貼り直すといった手間が生じていましたが、Mermaid を使うことで作業効率も大幅に向上します。
ソフトウェア開発のドキュメント作成やアジャイル開発の現場、さらには ビジネス要件整理 や 研究資料の可視化 にも、Mermaid は大いに役立ちます。

もしまだ使ったことがない方は、まずは簡単なフローチャート を試しに書いてみるところから始めてみましょう。一度慣れてしまえば、その利便性から手放せなくなるはずです。

用語集