Markdown で Mermaid 図を描く：フローチャート、シーケンス図など

図は、何段落もの文章よりもプロセス、アーキテクチャ、スケジュールをうまく伝えてくれます。しかし、グラフィックエディターで描くとなると、画像をエクスポートし、ドキュメントの隣に保存し、何か変わるたびにすべて描き直さなければなりません。

Mermaid はこの問題を解決します。Markdown ファイルの中に数行のテキストで図を記述すれば、プレビューアーが描画してくれます。図は同じファイルの中にあり、差分にも表示され、文章と同じくらい簡単に更新できます。GitHub、GitLab、Obsidian、多くのドキュメントジェネレーター、そして Markdown Preview Editor は、Mermaid を標準で表示できます。

Mermaid 図の追加方法

コードブロックを作り、言語を mermaid に設定します。

markdown```mermaid
flowchart LR
  A[書く] --> B[プレビュー]
  B --> C{完成？}
  C -- はい --> D[出力]
  C -- いいえ --> A
```

プレビューアーはこれを次のように描画します。

1 行目で図の種類を指定します。それ以降の行でノードと接続を記述します。

フローチャート

フローチャートは最もよく使われる図の種類です。キーワードの後に方向を書きます：TD または TB（上から下）、BT、LR（左から右）、RL。

mermaidflowchart TD
  start([開始]) --> input[/ファイルを読み込む/]
  input --> valid{有効か？}
  valid -- はい --> save[(データベースに保存)]
  valid -- いいえ --> error[エラーを表示]
  error --> input

ラベルを囲むかっこの種類でノードの形が決まります。

接続：--> は矢印、--- は矢印なしの線、-.-> は点線の矢印、==> は太い矢印です。ラベルは -- text --> または -->|text| で付けます。

関連するノードは subgraph でグループ化できます。

mermaidflowchart LR
  subgraph Browser
    editor[エディター] --> preview[プレビュー]
  end
  preview --> export[HTML / PDF]

シーケンス図

シーケンス図は、参加者どうしが時間の流れに沿ってどうメッセージをやり取りするかを表します。API、認証フロー、ユーザージャーニーの説明に最適です。

mermaidsequenceDiagram
  participant U as ユーザー
  participant A as アプリ
  participant S as サーバー
  U->>A: 「ログイン」をクリック
  A->>S: POST /login
  S-->>A: 200 OK + トークン
  A-->>U: ダッシュボードを表示
  Note over A,S: トークンは 1 時間で失効

->> は実線の矢印（リクエスト）、-->> は破線の矢印（レスポンス）です。Note over、Note left of、Note right of で注記を追加できます。繰り返しや分岐を表すには loop、alt/else、opt ブロックを使います。

ガントチャート

ガントチャートは、タスクの一覧をタイムラインに変換します。タスクは日付から始めることも、別のタスクの after（後）に始めることもできます。

mermaidgantt
  title ドキュメント作成スプリント
  dateFormat YYYY-MM-DD
  section 執筆
  構成案      :done,   a1, 2026-10-01, 2d
  初稿        :active, a2, after a1, 4d
  section レビュー
  ピアレビュー :        a3, after a2, 3d
  公開        :milestone, after a3, 0d

状態遷移図

状態遷移図は、注文、ドキュメント、UI コンポーネントなどが状態間をどう移り変わるかを表します。

mermaidstateDiagram-v2
  [*] --> Draft
  Draft --> Review : submit
  Review --> Draft : changes requested
  Review --> Published : approve
  Published --> [*]

円グラフ

全体に占める割合をさっと示したいときは、円グラフが便利です。1 行につき 1 つの項目を書きます。

mermaidpie title ドキュメント作業の時間配分
  "執筆" : 45
  "書式の調整" : 15
  "図を最新に保つ作業" : 40

Mermaid はほかにも、クラス図、ER 図、マインドマップ、タイムライン、Git グラフ、四象限チャートなどに対応しています。それぞれの記法は Mermaid の公式サイトで解説されています。

読みやすい図にするコツ

• 小さく保つ。 ノードが 15〜20 個を超えると読みにくくなります。1 つのアイデアにつき 1 つの図になるよう、複数の図に分けましょう。
• 方向は意図して選ぶ。 手順の少ないプロセスには LR、階層構造や長いフローには TD が向いています。特に画面幅の狭い端末では TD が見やすくなります。
• ID は短く、ラベルは読みやすく。 ラベルをそのまま ID にせず、auth[Check the session] のように書くと、接続の記述が短く済みます。
• 特殊文字を含むラベルは引用符で囲む： A["Price: $5 (incl. tax)"]。
• コメントを追加する。 行頭に %% を書くとコメントになり、描画時には無視されます。
• 入力しながらプレビューする。 矢印やかっこが 1 つ欠けるだけで図全体が壊れるので、リアルタイムプレビューがあれば試行錯誤が大幅に減ります。Markdown Preview Editor では編集に合わせて図が再描画され、「高度なエディター」ツールバーの Mermaid 図 ボタンでひな形を挿入できます。

図を含むドキュメントを共有する

ドキュメントを HTML や PDF にエクスポート すると、図は画像として含まれるので、読み手が Mermaid をインストールする必要はありません。図と一緒に数式を使うなら Markdown で数式を書く方法 を、表、タスクリスト、アラートなどそれ以外のことについては Markdown チートシート を手元に置いておきましょう。