Mermaid

Mermaid とは

Mermaid は、テキストベースの記法でフローチャート、シーケンス図、ER 図、ガントチャート、クラス図などを記述し、自動的に SVG にレンダリングするダイアグラムツールである。Knut Sveidqvist が開発し、2014 年 12 月に最初のバージョン (0.2.11) が npm へ公開された。GitHub は 2022 年 2 月から Markdown ファイル内の mermaid コードブロックをネイティブにレンダリングし、GitLab も公式に対応している。

画像編集ツールで図を作成する代わりに、コードとして図を管理できる。Git で差分を追跡でき、プルリクエストで図の変更をレビューできる。

主要な図の種類

フローチャート

graph TD
    A[ユーザーリクエスト] --> B{認証済み?}
    B -->|Yes| C[API 処理]
    B -->|No| D[401 Unauthorized]
    C --> E[レスポンス返却]

シーケンス図

sequenceDiagram
    Client->>API Gateway: POST /orders
    API Gateway->>Lambda: Invoke
    Lambda->>DynamoDB: PutItem
    DynamoDB-->>Lambda: Success
    Lambda-->>API Gateway: 201 Created
    API Gateway-->>Client: Response

ER 図

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ ORDER_ITEM : contains
    ORDER_ITEM }|--|| PRODUCT : references

状態遷移図

stateDiagram-v2
    [*] --> Draft
    Draft --> Pending: confirm
    Pending --> Paid: pay
    Paid --> Shipped: ship
    Draft --> Cancelled: cancel
    Pending --> Cancelled: cancel

GitHub での活用

GitHub の Markdown ファイル (README.md、Issue、PR) で Mermaid を直接レンダリングできる。

```mermaid
graph LR
    A[S3] --> B[CloudFront] --> C[ユーザー]
```

ADR (Architecture Decision Record) での活用

アーキテクチャの意思決定を記録する ADR に、Mermaid でシステム構成図やデータフローを埋め込む。テキストベースなので、アーキテクチャの変更履歴を Git で追跡できる。

Mermaid vs 他のツール

Mermaid と他のツールの違いを以下にまとめる。

ツール	形式	特徴
Mermaid	テキスト (Markdown 内)	GitHub ネイティブ、Git 管理可能
PlantUML	テキスト	UML に特化、Java 依存
draw.io	GUI	自由度が高い、XML 形式
Excalidraw	GUI	手書き風、コラボレーション

Mermaid はテキストベースで Git 管理できる点が最大の強み。複雑なレイアウトが必要な場合は draw.io や Excalidraw の方が適している。

よくある落とし穴

複雑すぎる図

Mermaid は自動レイアウトのため、ノードが多すぎると見づらくなる。1 つの図に 15 ノード以上は避け、複数の図に分割する。

埋め込み先のレンダラーが古い

Mermaid 本体の更新は速く、2026 年 8 月時点の最新は 11 系である。一方で埋め込み先のレンダラーは追随が遅れ、GitLab.com は公式ドキュメントで Mermaid 10 系をサポートすると明記している。手元の Live Editor で描けた図が、貼り付け先では構文エラーになることがある。新しい図種や構文を使うときは、実際に表示させる場所でレンダリングを確認する。

実務での活用方法は関連書籍にも詳しい。