Mermaid | Knowledge Garden

Mermaidは、テキストベースでダイアグラムを記述できるJavaScriptライブラリです。マークダウンライクな記法で、フローチャート、シーケンス図、ER図、ガントチャートなど様々なダイアグラムを作成できます。

概要

Mermaidとは

Mermaidは、2014年にKnut Sveidqvistによって作成されたオープンソースのダイアグラム生成ツールです。テキストで記述したコードからSVGまたはPNG形式のダイアグラムを生成します。

特徴

テキストベース: コードでダイアグラムを記述
バージョン管理が容易: Gitで差分管理が可能
学習コストが低い: シンプルな構文
豊富なダイアグラムタイプ: フローチャート、シーケンス図、クラス図など
広いプラットフォームサポート: GitHub、GitLab、Notion、VS Code等

主なユースケース

READMEやドキュメント内のダイアグラム
設計文書のフロー図
システムアーキテクチャ図
データベース設計（ER図）
プロジェクト計画（ガントチャート）

基本的な使い方

インストール

npmでのインストール

npm install mermaid

CDNでの利用

<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
<script>mermaid.initialize({ startOnLoad: true });</script>

基本的な初期化

import mermaid from 'mermaid';

mermaid.initialize({
  startOnLoad: true,
  theme: 'default', // 'default', 'dark', 'forest', 'neutral'
  securityLevel: 'loose',
});

HTMLでの使用

<pre class="mermaid">
graph TD
    A[開始] --> B{条件}
    B -->|Yes| C[処理A]
    B -->|No| D[処理B]
    C --> E[終了]
    D --> E
</pre>

サポートされるダイアグラムタイプ

1. フローチャート（Flowchart）

最も基本的なダイアグラムタイプです。

graph TD
    A[四角形] --> B(角丸四角形)
    B --> C{ひし形}
    C -->|Yes| D[結果1]
    C -->|No| E[結果2]

方向の指定

TB / TD: 上から下（Top to Bottom / Top Down）
BT: 下から上（Bottom to Top）
LR: 左から右（Left to Right）
RL: 右から左（Right to Left）

ノードの形状

graph LR
    A[四角形]
    B(角丸四角形)
    C([スタジアム型])
    D[[サブルーチン]]
    E[(データベース)]
    F((円形))
    G>非対称]
    H{ひし形}
    I{{六角形}}
    J[/平行四辺形/]
    K[\逆平行四辺形\]

接続線のスタイル

graph LR
    A --> B
    A --- C
    A -.- D
    A -.-> E
    A ==> F
    A --テキスト--> G
    A -.テキスト.-> H

2. シーケンス図（Sequence Diagram）

システム間のやり取りを時系列で表現します。

sequenceDiagram
    participant U as ユーザー
    participant C as クライアント
    participant S as サーバー
    participant D as データベース

    U->>C: ログインボタンクリック
    C->>S: POST /login
    S->>D: ユーザー検索
    D-->>S: ユーザー情報
    S-->>C: 認証トークン
    C-->>U: ダッシュボード表示

メッセージの種類

sequenceDiagram
    A->>B: 実線矢印（同期）
    B-->>A: 点線矢印（応答）
    A-)B: 実線矢印（非同期）
    B--)A: 点線矢印（非同期応答）
    A-xB: 実線×（失敗）

ループと条件分岐

sequenceDiagram
    participant C as Client
    participant S as Server

    loop 毎秒
        C->>S: ポーリング
        S-->>C: データ
    end

    alt 成功
        S-->>C: 200 OK
    else 失敗
        S-->>C: 500 Error
    end

    opt オプション処理
        C->>S: 追加リクエスト
    end

3. クラス図（Class Diagram）

オブジェクト指向設計のクラス構造を表現します。

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound()
    }
    class Dog {
        +String breed
        +bark()
    }
    class Cat {
        +String color
        +meow()
    }

    Animal <|-- Dog
    Animal <|-- Cat

関係性の表現

classDiagram
    classA <|-- classB : 継承
    classC *-- classD : コンポジション
    classE o-- classF : 集約
    classG --> classH : 関連
    classI -- classJ : リンク
    classK ..> classL : 依存
    classM ..|> classN : 実装

4. ER図（Entity Relationship Diagram）

データベース設計を表現します。

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ ORDER_ITEM : contains
    PRODUCT ||--o{ ORDER_ITEM : "ordered in"

    USER {
        int id PK
        string name
        string email UK
        datetime created_at
    }

    ORDER {
        int id PK
        int user_id FK
        datetime order_date
        string status
    }

    PRODUCT {
        int id PK
        string name
        decimal price
    }

    ORDER_ITEM {
        int id PK
        int order_id FK
        int product_id FK
        int quantity
    }

カーディナリティ

||--||: 1対1
||--o{: 1対多（0以上）
||--|{: 1対多（1以上）
}o--o{: 多対多

5. ガントチャート（Gantt Chart）

プロジェクトのスケジュールを表現します。

gantt
    title プロジェクトスケジュール
    dateFormat YYYY-MM-DD
    
    section 企画
    要件定義     :a1, 2024-01-01, 30d
    設計         :a2, after a1, 20d
    
    section 開発
    フロントエンド :b1, after a2, 40d
    バックエンド   :b2, after a2, 45d
    
    section テスト
    単体テスト    :c1, after b1, 10d
    結合テスト    :c2, after c1, 15d
    
    section リリース
    デプロイ      :d1, after c2, 5d

6. マインドマップ（Mind Map）

アイデアや情報の構造を表現します。

mindmap
  root((中心テーマ))
    トピック1
      サブトピック1-1
      サブトピック1-2
    トピック2
      サブトピック2-1
        詳細2-1-1
        詳細2-1-2
      サブトピック2-2
    トピック3

7. 状態遷移図（State Diagram）

システムの状態変化を表現します。

stateDiagram-v2
    [*] --> 待機中
    待機中 --> 処理中 : 開始
    処理中 --> 完了 : 成功
    処理中 --> エラー : 失敗
    エラー --> 待機中 : リトライ
    完了 --> [*]

8. 円グラフ（Pie Chart）

データの比率を表現します。

pie title 言語使用率
    "JavaScript" : 45
    "Python" : 25
    "TypeScript" : 20
    "その他" : 10

スタイリングとテーマ

組み込みテーマ

mermaid.initialize({
  theme: 'default', // デフォルト
  // theme: 'dark',   // ダークテーマ
  // theme: 'forest', // フォレストテーマ
  // theme: 'neutral', // ニュートラルテーマ
});

カスタムスタイル

graph LR
    A[開始]:::startClass --> B[処理]
    B --> C[終了]:::endClass

    classDef startClass fill:#90EE90,stroke:#333
    classDef endClass fill:#FFB6C1,stroke:#333

インラインスタイル

graph LR
    A[開始] --> B[処理]
    style A fill:#f9f,stroke:#333,stroke-width:2px
    style B fill:#bbf,stroke:#333

プラットフォーム別の使用方法

GitHub

GitHubのマークダウンファイルで直接使用できます。

```mermaid
graph LR
    A --> B --> C
```

VS Code

Markdown Preview Mermaidなどの拡張機能をインストールすると、プレビューでダイアグラムが表示されます。

Notion

/codeブロックで言語をMermaidに設定すると表示されます。

ベストプラクティス

1. シンプルに保つ

複雑すぎるダイアグラムは読みにくくなります。必要に応じて分割しましょう。

2. 一貫した命名規則

ノードIDは意味のある名前を使用します。

graph TD
    userInput[ユーザー入力] --> validation{バリデーション}
    validation -->|OK| processing[処理実行]
    validation -->|NG| errorMessage[エラー表示]

3. コメントを活用

graph TD
    %% ユーザー認証フロー
    A[ログイン画面] --> B{認証}
    B -->|成功| C[ダッシュボード]
    B -->|失敗| D[エラー画面]

4. 方向を適切に選択

縦長のフロー: TD / TB
横長のフロー: LR
プロセスの流れ: LR が読みやすい

制限事項

インタラクティブ性がない

Mermaidは静的なダイアグラムを生成します。ノードのドラッグ&ドロップや動的な編集はできません。

レイアウトの制御が限定的

自動レイアウトのため、ノードの位置を細かく制御することは困難です。

複雑なダイアグラムには不向き

数十個以上のノードがある複雑なダイアグラムは、専用のツール（React Flow、GoJS等）を検討してください。

概要