mermaid-diagrams

Mermaid：図の作成とレンダリング

概要

Mermaid の図を作成して検証します。Mermaid はテキストから図を生成する言語です。Markdown 内のフェンス付き ```mermaid ブロックは GitHub（およびほとんどのほかのホスト）でネイティブにレンダリングされるため、図は画像ではなく、テキストとしてコミットします。画像を生成するのは、ローカルで検証するときだけです。プッシュする前に mmdc でブロックを SVG／PNG にレンダリングし、構文が正しく、読みやすいことを確認します。

@mermaid-js/mermaid-cli（mmdc）v12.0.0 およびヘッドレス Chromium 154 で検証済みです。フラグは最近のリリース間で安定していますが、コマンドが予期せず動作する場合は mmdc --help を実行してください。

重要なポイント： 難しいのは Mermaid の構文ではなく、コンテナ内でヘッドレス Chromium をレンダリングすることです。mmdc は実際の Chromium ブラウザーを操作して図をラスタライズします。Chromium のサンドボックスにはユーザー名前空間が必要ですが、root 以外のコンテナユーザーでは利用できないため、そのままの mmdc は起動に失敗します。--no-sandbox --disable-setuid-sandbox --disable-dev-shm-usage を指定した Puppeteer 設定が必須です。docker-opencode イメージにはこの設定が組み込まれており、自動的に適用する mermaid-render ラッパーが付属しています。

使用する場合／しない場合

• Markdown 内の ```mermaid ブロックを作成、編集、検証するときや、Markdown でアーキテクチャ図／フロー図／シーケンス図／状態図／ER 図を求められたときに使用します。
• 単独の画像ファイル、チームが専用ツールで管理する C4 モデル、または手動で正確なレイアウトが必要な図（Mermaid は自動でレイアウトします。代わりに専用の図作成ツールを使います）には、Mermaid を使用しないでください。
• コミットする PNG／SVG 画像より Mermaid を優先します。差分を確認でき、レビュー可能で、ホスト上で無料で再レンダリングできます。

前提条件

• PATH 上に mmdc があること — @mermaid-js/mermaid-cli（docker-opencode イメージに組み込み済み。それ以外の場合は npm install -g @mermaid-js/mermaid-cli）。
• サンドボックスを無効にする Puppeteer 設定があること（イメージでは ~/.config/mermaid/puppeteer.json に組み込み済み）：

  {"args":["--no-sandbox","--disable-setuid-sandbox","--disable-dev-shm-usage"]}
  

• mermaid-render ラッパーがあること（イメージでは PATH 上に組み込み済み）。mmdc -p <config> をラップするため、フラグを繰り返し指定する必要はありません。

レンダリングと検証のワークフロー

mmdc が受け取るのはファイルであり、フェンス付きブロックではありません。そのため、各 ```mermaid ブロックを一時 .mmd ファイルに抽出してレンダリングし、出力を確認します。このループは、任意の数の図に対応します（実際の複数図を含む architecture.md で検証済みです）。

1. Markdown ファイルにブロックを記述します（フェンス付きの mermaid）。
2. ファイル内のすべての Mermaid ブロックを /tmp/d-<n>.mmd に分割します：

   awk '
     /^```mermaid[[:space:]]*$/ { n++; inblk=1; next }
     /^```[[:space:]]*$/        { inblk=0 }
     inblk                       { print > ("/tmp/d-" n ".mmd") }
   ' FILE
   

3. それぞれをレンダリングし、空でない出力が生成されたことを確認します：

   for f in /tmp/d-*.mmd; do
     if mermaid-render "$f" && [ -s "${f%.mmd}.svg" ]; then
       echo "OK:   $f"
     else
       echo "FAIL: $f"
     fi
   done
   

   図が1つだけの場合は、mermaid-render /tmp/d-1.mmd を実行します。ラッパーを使わずに直接レンダリングする場合： mmdc -i /tmp/d-1.mmd -o /tmp/d-1.svg -p ~/.config/mermaid/puppeteer.json。PNG の場合：mermaid-render -i /tmp/d-1.mmd -o /tmp/d-1.png。
4. 検証：レンダリングが終了コード 0 で終了し、空でないファイルを書き出した場合にのみ、ブロックは正常です。構文エラーは標準エラーに出力され、出力が生成されないか空になります。FAIL があれば「ブロックが壊れている」と判断し、SVG を開いて修正します。
5. すべてのブロックが OK になるまで繰り返してから、プッシュします。一時ファイルは rm ではなく上書きしてください（ブロックされる場合があります）：echo "" > /tmp/d-*.mmd。

図の種類の選び方

必要な内容	Mermaid の種類
コンポーネントと相互連携、リクエスト／データの経路、コントロールプレーン	flowchart TD（または LR）
名前付きの参加者間で時間経過に沿って行われるメッセージのやり取り	sequenceDiagram
状態と遷移	stateDiagram-v2
クラス／オブジェクトの関係	classDiagram
データモデル／テーブル	erDiagram
システムコンテキスト／C4 レベル 1	C4Context（c4-mermaid インクルード経由）、またはラベル付きの flowchart
ロードマップ／スケジュール	gantt
比率	pie

「システムの全体像と各部分の通信方法」を示す概要図（architecture.md のユースケース）には、通常 flowchart TD または flowchart LR が適しています。subgraph を使って、コンポーネントをレイヤー（エッジ／データプレーン／コントロールプレーン／ストレージ）ごとにまとめ、エッジにはやり取りの内容（-->|"SQL"|）をラベルとして付けます。

コマンドリファレンス

コマンド	用途
mermaid-render file.mmd	file.svg にレンダリングします（ラッパー。サンドボックス無効の設定を自動適用）
mermaid-render -i in.mmd -o out.svg	入出力を明示します
mermaid-render -i in.mmd -o out.png	ラスター画像として出力します
mermaid-render -i in.mmd -o out.svg -b transparent -s 2	背景を透明にし、スケールを 2 倍にします
mmdc -i in.mmd -o out.svg -p ~/.config/mermaid/puppeteer.json	ラッパーを使わずに直接実行します（設定フラグが必要です）
mmdc --help	フラグの詳細なリファレンス

よく使う mmdc フラグ：-i/--input、-o/--output、-b/--backgroundColor（white／transparent）、-s/--scale、-w/--width、-p/--puppeteerConfigFile、-f/--find（指定した ID の図のみをレンダリングします）。

作成時の注意点

1. 特殊文字を含むノードラベルは引用符で囲みます。 ()、{}、[]、#、引用符を含むラベルや、単純なケース以外のラベルは、二重引用符で囲んでください：A["VTGate (edge)"]。特殊文字を引用符で囲まないと、構文解析に失敗します。
2. ラベル内の改行には <br/> を使います。 A["line one<br/>line two"]。引用符で囲まれていないラベルに生の改行を入れると、構文エラーになります。
3. ノードの形状を意図的に選びます。 [rect]、(round)、((circle))、[[subroutine]]、>flag]、{decision}。形状に一貫性がない使い方は避けてください。形状には意味があります。
4. スペースを含む subgraph のタイトルは引用符で囲みます — subgraph sg1["Data plane"]。
5. エッジラベルには -->|"label"| または -- text --> を使います。短くまとめてください。長い説明文は図ではなく周囲のテキストに記載します。
6. # はコメントのように扱われる文字です。 ラベル内で # をそのまま使わないでください（ラベルを引用符で囲むか、別の表現にします）。
7. 図は内容ごとに分けます。 ノードが 30 個ある複雑な図は概要図とは言えません。巨大なグラフを 1 つ作るのではなく、「概要」「データ経路」「コントロール経路」に分割してください。各図のレンダリングが速くなり、読みやすさも保てます。
8. ID は一意で ASCII 文字のみを使います。 ノード ID は短く（v1、vg）、人が読む名前はラベルに記載します。
9. コメントは %% です — そのまま残しても問題ありません。レンダリング前に除去されます。
10. C4 ではブロックの先頭にインクルードが必要です。 判断に迷う場合は、ラベル付きの flowchart を使えば、追加の依存関係なしで同じコンテキストを伝えられます。

検証

• 構文とレンダリング：mermaid-render /tmp/d.mmd && [ -s /tmp/d.svg ] — 両方が成功する必要があります。
• 読みやすさ：SVG を開く（または小さな PNG にレンダリングする）などして、ラベルが読みやすく、重なっていないことを確認します。レンダリングできてもラベルが重なっている図は失敗です。
• GitHub プレビュー：GitHub は同じ Mermaid エンジンを使用するため、mmdc で問題なくレンダリングできるブロックは GitHub でも表示されます。画像をコミットする必要はありません。

チェックリスト

• Markdown ファイル内でブロックが ```mermaid としてフェンスされています
• 特殊文字を含むノード／エッジのラベルが二重引用符で囲まれています
• スペースを含む subgraph のタイトルが引用符で囲まれています
• すべての図がレンダリングされます：mermaid-render が終了コード 0 を返し、出力が空ではありません
• 図が読みやすく、ラベルが重なっていません。密度が高すぎる場合は分割してください
• 図は概要レベルにとどめ、詳細はリンク先の説明文／機能ファイルに記載されています
• PNG／SVG をコミットせず、テキストブロックのみをコミットしています
• 一時 .mmd ファイル／出力ファイルは削除するだけでなく、上書きされています