mozumasu/dotfiles/mermaid-writing

Mermaid Writing

Mermaid 図を書くとき、特に GitHub の PR / issue / README に埋め込むときの規律。 GitHub は独自バージョンの mermaid でレンダリングするため、mermaid.live で通る図が 「Unable to render rich display」で落ちることがある。エラー詳細は表示されない。

GitHub 向けの安全記法 (実測ベース)

PR 本文で実際に描画失敗 → 修正で解消した経験則。複数要素を同時に変えたため 決定打は未切り分けだが、以下を全部守れば落ちなかった:

• エッジラベルは `-- "テキスト" -->` 記法を使う。-->|"テキスト"| は GitHub で

落ちたことがある (mermaid.live では通る)

• ノード定義とエッジ定義を分離する。A["ラベル"] -->|"..."| B["ラベル"] のような

1 行複合より、先にノードを全部定義してからエッジを並べる方が壊れにくく diff も読みやすい

• ノードラベルは常にダブルクォートで囲む。( ) [ ] { } はクォートなしだと

ノード形状の記法として解釈される

• ラベル内の記号は最小限にする。全角の 「」・（）・： は避け、改行は <br/> のみ使う

(他の HTML タグは使わない)

記法の落とし穴 (GitHub に限らない)

• ノード id に end を使うと flowchart が壊れる (予約語)。o / x で始まる id も

エッジ記号 (--o / --x) と誤解されうる。id は英大文字始まりが無難

• %% 以降はコメント。ラベル内に %% を書かない
• subgraph のタイトルもクォートする: subgraph caller["呼び出し側"]
• classDef / class での色指定は GitHub のダーク/ライト両テーマで見えるか意識する

(濃色塗り + 白文字の組み合わせが安全)

検証方法

書いたら投稿前に検証する。GitHub 上の失敗はエラー詳細が出ず、投稿してみるまで 分からないため、事前検証の価値が高い:

# mermaid-cli があれば構文 + レンダリングをローカル検証できる
npx -y @mermaid-js/mermaid-cli -i diagram.mmd -o /tmp/diagram.svg

• mmdc が使えない環境では、上の安全記法に全部従っているかをセルフチェックする
• それでも GitHub で落ちたら、原因調査に時間をかけず **テキスト図 (コードブロック内の

ASCII 図) に差し替える**。レンダリング事故が原理的に起きず、情報量は保てる

図の選び方

• フロー・依存関係 → flowchart LR (横) / flowchart TD (縦)。ノード 10 個を超えるなら

分割を検討する

• 時系列のやり取り → sequenceDiagram
• 状態遷移 → stateDiagram-v2
• 表で足りる内容に mermaid を使わない。構造が 1 次元なら箇条書きかテーブルの方が読める