Mermaid

mermaid

図はテンプレートを埋めて作るものではない。 何を見せたいかを決め、それに図が要るかを判断し、要るなら図種を選ぶ。

1. 図にするかを決める

図は表より高価である。 縦幅を奪い、差分が読みにくく、構文を誤ると図全体がエラー表示になる。 GitHub では図が iframe の中に入るため、本文検索にもスクリーンリーダーにもかからない。

判定はこの一言で足りる。

この図を表に書き直したとき、失われる情報はあるか。無ければ表にする。

図が固有に持つのは位相(分岐、合流、循環)だけであり、個々の値ではない。 ノードのラベルが隣の表の行をなぞっているなら、その図は表の再掲に辺を足しただけになる。 ノード2個で辺1本の図は、本文に A → B と書けば足りる。

表が確実に優るのは次の場合である。

• ノードが2個から3個しかない
• 1対1対応の二部グラフになる(要件と成果物の対応など)。これは定義上テーブルと同型で、しかも表なら列を無料で足せる
• 順序が本質で分岐が無い(番号付きリストが正確)
• 値の比較が目的である

2. 図種を決める

見せたいもの	図種
依存や工程の構造、分岐と合流	flowchart
1つの対象が辿る状態と、戻る経路	stateDiagram-v2
登場人物の間の時系列のやり取り	sequenceDiagram
データの実体と関係	erDiagram

選ばない判断も持っておく。

• gantt:各項目に日付か期間が必須のため、時間軸を持たない計画には使えない
• mindmap:単一ルートの木であり、合流(fan-in)を表せない
• kanban:カード間に辺を描けない(実装が常に空の辺集合を返す)。accTitle も書けない
• requirementDiagram:グルーピングが無く、ノードの最小寸法が200pxのため、要件が10件を超えると破綻する

要件のカバレッジは図より表が向く。 「どの要件が未カバーか」を伝えるだけなら、表の1列にチェックを置くほうが速く正確である。

3. GitHub 上での制約

GitHub は mermaid をサーバで描画せず、クロスオリジンの iframe に渡して描画する。 以下の制約はほぼすべてこの構造に由来する。

• click は効かない:関数呼び出しは securityLevel で無効化され、URL リンクは CSP で遮断されるため、リンクは図の外の表に置く
• theme を指定しない:GitHub は iframe にテーマを渡してライトとダークを自動追随させており、theme を書くとこれを殺す(色を変えたいときは themeVariables だけを使う)
• layout: elk は使わない:GitHub には elk が登録されておらず、エラーを出さずに dagre へ無言でフォールバックするため、書いても効かないことに気づけない
• 上限はテキスト50000文字と辺500本である。これらは呼び出し側しか変更できず、%%{init}%% でも上書きできない
• 構文エラーでは部分描画されず図全体がエラーになるので、貼る前に構文を確かめる

使えるバージョンの確かめ方

GitHub が使う mermaid のバージョンは告知されない。 公式に案内されている確認手段は、対象のリポジトリで次の1行を書いて描画させることだけである。

info

調査時点の github.com では 11.16.0 が表示された(上流の最新安定版と同一)。 新しい図種を採用する前は、この手順で自分の環境のバージョンを確かめる。

4. 貼る前に描画して形を見る

構文が通ることと、読めることは別である。 構文検査だけで貼ると、レイアウトが破綻した図をそのまま出すことになる。 貼る前に描画し、次の3点を確認する。

流れの向きが反転していないか

戻り線が全体の循環を作ると、レイアウトエンジンは順序を決められず、始点が図の末尾に置かれることがある。 差し戻しや再試行を元の工程へ戻す辺を素直に書くと、これが起きる。

対策は循環を断つこと。 差し戻しの宛先を1つの終端ノード(「人間へ戻す」など)に集約し、そこから本流へ戻す辺は引かない。 戻り先が近い局所的な戻り線(直前の工程へ戻すだけ)は循環が短く、順序を壊しにくい。

表示幅に収まるか

GitHub は図を本文の幅(およそ800px)に合わせて縮小する。 横に広い図は全体が縮み、文字が読めない大きさになる。 描画して幅を測り、800px を大きく超えるなら、TD に変えるか、図を分割する。 縦に長い図は縮小されないが、スクロールが増えるため、目安として高さ1200px を超えたら分割を検討する。

1つの図が1つのことを言っているか

全体像と詳細を1枚に詰めると、どちらも読めなくなる。 「全体の流れ」と「1件の内側の流れ」のように分け、図の外の文で繋ぐ。

5. 壊さないための記法

• ノードのラベルはダブルクォートで囲む(#、/、() を含むため)
• 強調はマークダウン文字列 "`**太字**`" を使う。<b> は文書化されておらず GitHub 側の挙動が変わった実績がある
• 通常のラベルでの改行は <br/> を使う(\n は改行にならない)。マークダウン文字列の中では改行文字がそのまま改行になる
• end をノード ID にしない(subgraph を閉じる予約語)
• requirementDiagram の text: に日本語を書くときは引用符で囲む(囲まないと lexical error になる)
• subgraph の中の direction は、その subgraph のノードが外部と繋がっていると無視される。 親グラフの向きを継承するため、指定しても効かない場面が多い

6. 凡例をグラフの中に作らない

mermaid に凡例の機能は無い。 subgraph で凡例を代用する書き方が広まっているが、次の2つの害がある。

1. linkStyle の番号が壊れる:linkStyle は宣言順の0始まりの通し番号でグラフ全体を数えるため、凡例に辺を足すと本体の辺に当てていた色指定がすべてずれる(レビューで気づけない壊れ方をする)
2. レイアウトを侵食する:レイアウトエンジンが凡例のノードを本体と同格に扱い、凡例が図の上部を占めて本体より先に目に入る(実測では、ノード2個の計画図で凡例が描画面積の50%と高さの69%を占めた)

凡例は図の外に markdown の1行として書き、実際に出現した状態だけを載せる。 図の外に出すと、本文検索とスクリーンリーダーの対象にもなる。 使われていない状態を凡例に残すと、その状態が存在するかのように読める。

7. 色と強調は意味にだけ使う

classDef で状態ごとに定義し、class でまとめて当てる。

classDef done fill:#2da44e,stroke:#1a7f37,color:#fff
class T1,T2 done

線の強調には linkStyle の番号指定ではなく ==> を使う。 番号指定は辺を1本足すたびに全体がずれるため、編集に弱い。

装飾のための色を足さない。 色で表した情報をラベルにも書いているなら、どちらかが冗長である。

8. 代替テキストを付ける

GitHub は「すべての図が支援技術に対応しているわけではない」と自ら明示している。 図の意味は書き手が補う。

flowchart LR
    accTitle: issue 123 のタスク依存関係
    accDescr: 設計から実装とテストを経てリリースに至る依存グラフ。T3 がブロック中。

accTitle は1行しか書けない。 複数行の説明は accDescr { ... } の波括弧の形を使う(この形にはコロンを付けない)。

kanban と mindmap は accTitle と accDescr を受け付けない。 これらを使う場合は、図の外の markdown で説明を補う。