IT 技書の森

Mermaid

Markdown 内にテキストベースで図表を記述し、自動的にレンダリングするダイアグラム記法

ドキュメントオブザーバビリティ

Mermaid とは

Mermaid は、テキストベースの記法でフローチャート、シーケンス図、ER 図、ガントチャート、クラス図などを記述し、自動的に SVG にレンダリングするダイアグラムツールである。2019 年に Knut Sveidqvist が開発し、GitHub、GitLab、Notion が Markdown 内の Mermaid 記法をネイティブにサポートしている。

画像編集ツールで図を作成する代わりに、コードとして図を管理できる。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 テキスト (Markdown 内) GitHub ネイティブ、Git 管理可能
PlantUML テキスト UML に特化、Java 依存
draw.io GUI 自由度が高い、XML 形式
Excalidraw GUI 手書き風、コラボレーション

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

よくある落とし穴

複雑すぎる図

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

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

関連用語