開発者向け「Mermaidダイアグラム」クイックスタート＆チートシート

Mermaidは、キャンバス上でボックスをドラッグするよりも、図をテキストとして記述することを好む人々のためのテキストベースの図作成ツールです。Markdownのような構文を使用して、フローチャート、シーケンス図、クラス図、状態機械図、タイムライン、ガントチャート、エンティティ関係図などを記述します。

技術ブログにおいて、Mermaidは非常に優れたデフォルト選択肢です。図は記事のすぐ側に存在し、Gitでレビュー可能であり、システムが変更された際に更新も容易です。静的な画像図は、最初のアーキテクチャ変更が行われるまで美しく見えます。Mermaidの図は完璧ではありませんが、時間の経過に耐える力（エイジング）は格段に優れています。

本ガイドは、開発者、技術ライター、Hugoサイト運営者向けのMermaidの実践的なクイックスタートおよびチートシートです。これは2026年のドキュメントツール：Markdown、LaTeX、PDFおよび印刷ワークフローハブの一部です。

Mermaidとは？

Mermaidは「コードとしての図（diagram-as-code）」の構文です。小さなテキストブロックを記述すると、Mermaidがそれを図としてレンダリングします。

基本的なMermaid図は以下のようになります：

このコード：

```mermaid
flowchart TD
    A[Write Markdown] --> B[Add Mermaid block]
    B --> C[Render page]
    C --> D[Publish diagram]
```

以下のような図を生成します：

重要なコンセプトはシンプルです：図のソースはプレーンテキストです。これにより、図は検索可能、レビュー可能、移植性が高く、説明するドキュメントと一緒に維持しやすくなります。

技術ブログでMermaidを使用する理由

Mermaidは、記事に文章以上の情報が必要だが、完全なデザインツールまでは必要ない場合に役立ちます。

Mermaidを使用すべき場面：

• リクエストとレスポンスのフロー
• デプロイメントパイプライン
• サービス間の依存関係
• 状態遷移
• データベース関係
• ユーザージャーニー
• ビルド手順
• 決定ロジック
• プロジェクトのタイムライン

すべてのビジュアルにMermaidを使用する必要はありません。スクリーンショット、手描きのアーキテクチャスケッチ、仕上がり度の高いマーケティング用図には依然として役割があります。しかし、エンジニアリングドキュメントにおいては、Mermaidは最もメンテナンスしやすい選択肢であることが多いです。

Mermaidクイックスタート

基本的なMarkdownの使用法

Markdownでは、mermaidを言語として指定したフェンス付きコードブロックを使用します。

```mermaid
flowchart LR
    A[Start] --> B[Process]
    B --> C[Done]
```

多くのプラットフォームはこの形式を直接理解します。mermaidは、diffやgeojsonなどと同様に、特定のレンダラーがプレーンな構文ハイライトではなく第一級ブロックタイプとして扱う特殊な言語識別子の一つです。フェンス付きブロック構文とサポートされる言語識別子の詳細な解説については、Markdownコードブロックガイドを参照してください。Hugoにおけるレンダリングは、テーマまたはサイト設定に依存します。その点は後述します。

公開前に図をテストする

最も簡単なワークフローは以下の通りです：

1. Markdownファイルに図を記述する。
2. Mermaidライブエディターまたはローカルプレビューに貼り付ける。
3. 構文エラーを修正する。
4. Markdownソースをコミットする。
5. 最終的なレンダリングされたページを確認する。

これにより、小さな構文の詳細の違いにより、あるレンダラーでは動作するが別のレンダラーでは壊れてしまうという古典的な問題を回避できます。

フローチャート構文

フローチャートはMermaid図の中で最も一般的なタイプです。ワークフロー、アルゴリズム、決定木、システム手順に使用します。

基本的なフローチャート

このコード：

```mermaid
flowchart TD
    A[User opens website] --> B{Is user logged in?}
    B -->|Yes| C[Show dashboard]
    B -->|No| D[Show login page]
```

以下のような図を生成します：

フローチャートの方向

Mermaidフローチャートは複数の方向をサポートしています：

TD - 上から下
TB - 上から下
BT - 下から上
LR - 左から右
RL - 右から左

例：

このコード：

```mermaid
flowchart LR
    Browser --> CDN
    CDN --> WebServer
    WebServer --> Database
```

以下のような図を生成します：

ブログ記事では、アーキテクチャ図の場合、LR（左から右）の方が読みやすいことが多いです。ステップバイステップのプロセスでは、TD（上から下）の方が適している場合が多いです。

一般的なノード形状

このコード：

```mermaid
flowchart TD
    A[Rectangle]
    B(Rounded rectangle)
    C{Decision}
    D((Circle))
    E[(Database)]
    F[[Subroutine]]
```

以下のような図を生成します：

フローチャートの矢印

このコード：

```mermaid
flowchart LR
    A --> B
    B --- C
    C -.-> D
    D ==> E
    E -- Label --> F
```

以下のような図を生成します：

サブグラフ

サブグラフを使用して、システムの関連する部分をグループ化します。

このコード：

```mermaid
flowchart LR
    subgraph Client
        Browser
    end

    subgraph Backend
        API
        Worker
    end

    subgraph Storage
        DB[(PostgreSQL)]
        Cache[(Redis)]
    end

    Browser --> API
    API --> DB
    API --> Cache
    API --> Worker
```

以下のような図を生成します：

サブグラフは強力ですが、慎重に使用してください。6つのサブグラフと20本の矢印を持つ図は、通常、記事を2つ以上の小さな図に分ける必要があるサインです。

シーケンス図構文

シーケンス図は、アクターやサービス間の時間経過に伴う通信を示します。

このコード：

```mermaid
sequenceDiagram
    participant User
    participant App
    participant API
    participant DB

    User->>App: Click login
    App->>API: POST /login
    API->>DB: Validate credentials
    DB-->>API: User record
    API-->>App: Access token
    App-->>User: Show dashboard
```

以下のような図を生成します：

一般的なシーケンス矢印

->      矢印なしの実線
-->     矢印なしの点線
->>     矢印ありの実線
-->>    矢印ありの点線
-x      矢印ありの実線（クロス）
--x     矢印ありの点線（クロス）

アクティベーションバー

アクティベーションバーは、参加者が作業を行っているタイミングを明確にします。

このコード：

```mermaid
sequenceDiagram
    participant Client
    participant Server

    Client->>Server: Request data
    activate Server
    Server-->>Client: Response
    deactivate Server
```

以下のような図を生成します：

代替と条件

このコード：

```mermaid
sequenceDiagram
    participant User
    participant API
    participant Payment

    User->>API: Submit order

    alt Payment succeeds
        API->>Payment: Charge card
        Payment-->>API: Approved
        API-->>User: Order confirmed
    else Payment fails
        Payment-->>API: Declined
        API-->>User: Show error
    end
```

以下のような図を生成します：

シーケンス図はAPI記事に非常に適しています。単にどのようなコンポーネントが存在するかだけでなく、それらがどのように互いにやり取りするかを示すことができます。

クラス図構文

クラス図は、ドメインモデルやオブジェクト間の関係に役立ちます。

このコード：

```mermaid
classDiagram
    class User {
        +string id
        +string email
        +login()
        +logout()
    }

    class Order {
        +string id
        +float total
        +submit()
    }

    User "1" --> "*" Order
```

以下のような図を生成します：

クラス関係

<|-- 継承
*-- 合成
o-- 集約
--> 関連
-- リンク
..> 依存
..|> 実現

例：

このコード：

```mermaid
classDiagram
    Animal <|-- Dog
    Animal <|-- Cat
    User "1" --> "*" Order
    Order *-- OrderItem
```

以下のような図を生成します：

クラス図はすぐに冗雑になりがちです。ブログ投稿では、完全なアプリケーションモデルよりも、小さなドメインのスライスを使用することを優先してください。

状態図構文

状態図は、ものが時間とともにどのように変化するかを説明します。

このコード：

```mermaid
stateDiagram-v2
    [*] --> Draft
    Draft --> Review: submit
    Review --> Published: approve
    Review --> Draft: request changes
    Published --> Archived: archive
    Archived --> [*]
```

以下のような図を生成します：

状態図は以下に使用します：

• オーダーのライフサイクル
• デプロイメント状態
• 認証フロー
• バックグラウンドジョブの状態
• コンテンツ公開ワークフロー

状態図は過小評価されがちです。長い段落よりもビジネスロジックをよりよく説明できることが多いです。

エンティティ関係図構文

エンティティ関係図は、データベースモデルに役立ちます。

このコード：

```mermaid
erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ ORDER_ITEM : contains
    PRODUCT ||--o{ ORDER_ITEM : appears_in

    USER {
        string id
        string email
    }

    ORDER {
        string id
        datetime created_at
    }

    PRODUCT {
        string id
        string name
    }
```

以下のような図を生成します：

ER関係マーカー

||  正確に1つ
o|  0または1
}|  1つ以上
}o  0以上

ER図は、すべての列ではなく、関係を説明する際に最も効果的です。実装の詳細はマイグレーションやスキーマドキュメントに保持してください。

ガントチャート構文

ガントチャートは、プロジェクトのタイムラインに役立ちます。

このコード：

```mermaid
gantt
    title Documentation Migration Plan
    dateFormat  YYYY-MM-DD

    section Planning
    Audit current docs      :a1, 2026-06-01, 5d
    Define structure        :a2, after a1, 3d

    section Writing
    Rewrite guides          :b1, after a2, 10d
    Review and publish      :b2, after b1, 4d
```

以下のような図を生成します：

ガントチャートは内部計画投稿に役立ちますが、すぐに古くなる可能性があります。タイムライン自体が要点である場合に使用してください。

タイムライン構文

タイムラインは、リリース履歴、インシデント報告書、プロジェクトサマリーに適しています。

このコード：

```mermaid
timeline
    title API Evolution
    2024 : REST API launched
    2025 : Webhooks added
    2026 : Event streaming introduced
```

以下のような図を生成します：

順序が依存関係よりも重要な場合にタイムラインを使用します。因果的につながり方よりもイベントのシーケンスが重要な場合、タイムラインは焦点を適切な場所に保ち、一目で読みやすい状態を維持します。

パイチャート構文

パイチャートはサポートされていますが、注意が必要です。カテゴリが少なく、値が明確に異なる場合にのみ読みやすくなります。

このコード：

```mermaid
pie title Build Time by Step
    "Install dependencies" : 35
    "Run tests" : 45
    "Build assets" : 20
```

以下のような図を生成します：

個人的なアドバイス：値が近い場合やカテゴリが5つを超える場合は、テーブルを使用してください。適切にフォーマットされたテーブルは、スライスがほぼ同じように見えるパイチャートよりも、正確な数値をより正直に伝えることができます。

Gitグラフ構文

Gitグラフは、ブランチ戦略やリリースフローを説明するために使用できます。

このコード：

```mermaid
gitGraph
    commit
    branch feature
    checkout feature
    commit
    commit
    checkout main
    merge feature
    commit
```

以下のような図を生成します：

これは、Gitワークフロー、トランクベース開発、リリースブランチ、ホットフィックスに関する記事に役立ちます。基礎となるブランチングコマンドのクイックリファレンスが必要な場合は、GITチートシートが、マージおよびリベースワークフローと併せて最も一般的なコマンドをカバーしています。

Mermaidチートシート

図のタイプ

flowchart TD
sequenceDiagram
classDiagram
stateDiagram-v2
erDiagram
gantt
timeline
pie
gitGraph
mindmap
journey

フローチャート基本

flowchart TD
A[Text] --> B[Text]
A -->|Label| B
A -.-> B
A ==> B
A --- B

フローチャート形状

A[Rectangle]
A(Rounded)
A{Decision}
A((Circle))
A[(Database)]
A[[Subroutine]]
A>Flag]

シーケンス図基本

sequenceDiagram
participant A
participant B
A->>B: Message
B-->>A: Reply
activate B
deactivate B

シーケンスブロック

alt condition
else other condition
end

opt optional step
end

loop each item
end

par parallel task
and another task
end

クラス図基本

classDiagram
class User
class Order
User --> Order
User "1" --> "*" Order

状態図基本

stateDiagram-v2
[*] --> Idle
Idle --> Running
Running --> Done
Done --> [*]

ER図基本

erDiagram
USER ||--o{ ORDER : places
ORDER ||--|{ ORDER_ITEM : contains

コメント

Mermaidは%%でコメントをサポートしています。

このコード：

```mermaid
flowchart TD
    %% This is a comment
    A --> B
```

以下のような図を生成します：

HugoでのMermaidの使用

Hugoコンテンツは通常Markdownで記述されるため、MermaidはHugoベースの技術ブログに自然に適合します。正確なセットアップは、テーマとMarkdownレンダリング設定に依存します。

一般的な作成パターンは依然として同じです：

```mermaid
flowchart LR
    Markdown --> Hugo
    Hugo --> HTML
    HTML --> Browser
```

HugoテーマがすでにMermaidをサポートしている場合、追加の作業なしでレンダリングされる可能性があります。サポートしていない場合、通常はレンダリングフック、ショートコード、パーシャル、またはMermaid図を含むページでMermaidを読み込むためのテーマ設定が必要です。

実践的なHugoセットアップは以下のルールを目標とすべきです：

• Mermaidソースを通常のMarkdown記事内に保持する。
• Mermaidは必要なページでのみ読み込む。
• ほとんどのページが図を使用しない場合は、グローバルなJavaScriptを避ける。
• ローカルプレビュー中に図をテストする。
• 図のソースをGitで読みやすい状態に保つ。

技術ブログでは、フェンス付きコードブロックは移植性が高いため、カスタムショートコードよりも通常優れています。後でコンテンツをGitHub、別の静的サイトジェネレーター、またはドキュメントプラットフォームに移動する場合、標準的なフェンス付きMermaidブロックの方が再利用が容易です。

Mermaidのベストプラクティス

図を小さく保つ

図は記事を明確にするものであり、記事を置き換えるものではありません。読者がズームインする必要がある場合、図は多分大きすぎます。

良い図は通常以下の要素を持ちます：

• 1つのアイデア
• 明確な方向
• 短いラベル
• 少ない交差線
• 一貫した命名

複数の小さな図を優先する

巨大なシステム図1つを使用する代わりに、いくつかの焦点を絞った図を使用します：

• リクエストフロー
• デプロイメントトポロジー
• データモデル
• 状態ライフサイクル
• 障害パス

これは読者にとって、またモバイル画面にとっても優れています。

安定した名前を使用する

コード、API、またはドキュメントと一致する名前を使用します。それらが真に異なる概念でない限り、異なる図で同じものをAPI、Backend、Serverと呼び分けないでください。

重要な矢印にラベルを付ける

ラベルなしの矢印は単純なフローチャートには問題ありません。システム図では、ラベルはしばしば重要です。

このコード：

```mermaid
flowchart LR
    Web -->|HTTPS request| API
    API -->|SQL query| DB
    API -->|publish event| Queue
```

以下のような図を生成します：

巧妙な構文を避ける

Mermaidは多くのことを実行できます。しかし、すべての記事にそれが必要というわけではありません。将来のメンテナーがすぐに理解できる構文を優先してください。

必要に応じてラベルをクォートで囲む

ラベルにMermaidを混乱させる文字が含まれている場合は、それをクォートで囲みます。

このコード：

```mermaid
flowchart TD
    A["User clicks /checkout"] --> B["POST /api/orders"]
```

以下のような図を生成します：

これは、煩わしいレンダリング失敗を防ぐための小さな習慣です。

ダークモードを考慮する

多くのHugoサイトはダークモードをサポートしています。MermaidテーマまたはサイトCSSが、ライトモードとダークモードの両方で図が読みやすい状態であることを確認してください。

Mermaidの一般的な間違い

間違い1：詳細度过剰

悪いMermaid図は、しばしばすべての例外ケースを表示しようとしすぎます。これにより、技術的には完全ですが、実用的には読みにくくなります。修正方法はほぼ常に同じです：図を2つまたは3つの小さなものに分け、それぞれが1つの懸念事項をカバーするようにし、読者が十数本の交差する矢印を追跡することなしにロジックを追跡できるようにします。

間違い2：長いラベル

長いラベルは、幅広いボックスと醜いレイアウトを作成します。

このコードの代わりに：

```mermaid
flowchart TD
    A[The user submits the registration form with their email address and password]
```

以下のような図を生成します：

このコードを優先してください：

```mermaid
flowchart TD
    A[Submit registration form]
```

以下のような図を生成します：

詳細は図の下の段落で説明してください。

間違い3：不明確な方向

方向を選び、それに固執してください。ほとんどのプロセス図はTDを使用すべきです。ほとんどのアーキテクチャ図はLRの方が簡単です。

間違い4：Mermaidをデザインツールとして扱う

MermaidはFigmaではありません。ピクセルパーフェクトな図のために意図されたものではなく、その役割に無理やり合わせてしまうと、ただのフラストレーションにつながります。その強点は維持性であり、視覚的な完璧さではありません — そしてそのトレードオフは意図的なものです。

技術ブログ向けのMermaid SEOヒント

Mermaid図は技術記事をより有用にできますが、検索エンジンには依然としてテキストが必要です。図だけに依存しないでください。

SEOフレンドリーなMermaid記事のために：

• 記述的なH2およびH3見出しを使用する。
• 各図を近くのテキストで説明する。
• 重要なキーワードを通常の文章に含める。
• コード例をコピー可能にする。
• 複雑な図の下に代替テキストのような説明を追加する。
• 簡潔なフロントマターのタイトルと説明を使用する。
• レンダリングされたSVGの内部にすべての意味を隠さないようにする。

Mermaid図は記事を支援するべきです。重要な情報が存在する唯一の場所になってはいけません。

コピー＆ペースト用Mermaid例

APIリクエストフロー

このコード：

```mermaid
sequenceDiagram
    participant Client
    participant API
    participant Auth
    participant DB

    Client->>API: GET /account
    API->>Auth: Validate token
    Auth-->>API: Token valid
    API->>DB: Load account
    DB-->>API: Account data
    API-->>Client: 200 OK
```

以下のような図を生成します：

CIパイプライン

このコード：

```mermaid
flowchart TD
    A[Push commit] --> B[Install dependencies]
    B --> C[Run lint]
    C --> D[Run tests]
    D --> E[Build site]
    E --> F[Deploy]
```

以下のような図を生成します：

このパターンは、実際のCI設定に自然にマッピングされます。GitHub Actionsワークフローのステップバイステップ構文については、上記の図を実動作するパイプラインに変えたい場合、GitHub Actionsチートシートは便利なコンパニオンです。

公開ワークフロー

このコード：

```mermaid
stateDiagram-v2
    [*] --> Draft
    Draft --> Editing
    Editing --> Review
    Review --> Published
    Review --> Editing
    Published --> [*]
```

以下のような図を生成します：

シンプルなデータモデル

このコード：

```mermaid
erDiagram
    AUTHOR ||--o{ POST : writes
    POST ||--o{ COMMENT : receives

    AUTHOR {
        string id
        string name
    }

    POST {
        string id
        string title
        datetime published_at
    }

    COMMENT {
        string id
        string body
    }
```

以下のような図を生成します：

Mermaidを使用しないべき場合

以下の場合はMermaidを使用しないでください：

• 図が正確な視覚的なレイアウトを必要とする場合。
• デザインがブランドシステムと正確に一致する必要がある場合。
• 視覚要素が主に装飾的な場合。
• 図が多すぎるノードがあり、読み取れない場合。
• スクリーンショットの方がポイントを説明しやすい場合。
• コンテンツが稀に変更され、維持性よりも仕上がり度が必要な場合。

Mermaidは、生きている技術ドキュメントに優れています。プレゼンテーショングレードの芸術作品にはあまり適していません。印刷またはPDFコンテキストでのドキュメント品質の図については、LaTeXはTikZやpgfplotsなどのパッケージを提供し、はるかに大きなレイアウト制御を提供します — LaTeXチートシートは、LaTeXツールの残りと併せて図の包含をカバーしています。

最終的な考え

Mermaidは、開発者がすでにどのように作業しているかを尊重するため、技術ブログのための最高のツールの一つです：テキストファイル、Markdown、Git、コードレビュー、そして再現可能なビルド。図を取り巻くすべてのもの — 見出し、リスト、テーブル、コードブロック — については、Markdownチートシートが、このガイドの横に置いておくべきクイックリファレンスコンパニオンです。

最高のMermaid図は、最も複雑なものではありません。概念を明白にし、6ヶ月後でも編集が容易な状態を保っている図です。

Mermaidは、ドキュメントと一緒に存在すべき図のために使用してください。小さく保ち、読みやすく保ち、それらを記事のソースコードの一部として扱いましょう。