RenderMermaid

Mermaid 図の構文を検査し、PNG 画像に描画する。HTML ファイルを渡した場合は、図そのものを描画済みの SVG に置き換える。

図を書いたら、必ずこのツールで確認してから完了すること。 構文の誤りは実行するまで分からず、そのまま納品すると読み手の画面には図ではなくエラーが出る。

使い方

書いた図をその場で確かめる

RenderMermaid({ code: "graph TD\n  A[開始] --> B[終了]" })

output/diagrams/diagram.png に画像が出る。ReadImage でその画像を開き、意図した図になっているか目で確認すること。 構文が通ることと、図が意図どおりであることは別の話で、後者は画像を見ないと分からない。

ファイルの中の図をまとめて確かめる

RenderMermaid({ path: "output/report.html" })

ファイル内の Mermaid ブロックを全部検査する。.md と .html に対応。

HTML の場合は、成功した図を描画済みの SVG に差し替える（embed: false で抑制できる）。差し替え後は次のようになる:

その図を出すのにスクリプトも外部通信も要らなくなる
ファイルプレビュー（スクリプトを止めている）でも図が出る
元の Mermaid コードは data-mermaid-source 属性に残るので、後から直して作り直せる

書き換えるのは図のブロックだけで、ファイルの他の部分には一切触れない。 <script> も同じで、図が SVG になったあと使われなくなった Mermaid の読み込みが残っていても、それは消さない。ページの中身はそれを書いた側のもので、消してよいかどうかをこのツールは判断できない。消したいなら自分で Edit する。

Markdown は差し替えない。プレビューが Mermaid をそのまま描画するので、画像にすると拡大や文字選択ができなくなり劣化する。

出力の読み方

mermaid 11.15.0 — 2 diagram(s)
OK #1: output/diagrams/output_report-1.png — open it with ReadImage to check the diagram is what you meant.
FAILED #2: Parse error on line 3:
  line 3:   A[設定を読む (config.yaml)] --> B[起動]

画像の名前は元ファイルのパスから作る（output/report.html なら output_report）。同じ名前のファイルが別のフォルダにあっても、後から描いた図が前の図を上書きしない。

PNG は図の見た目の大きさの 2 倍の画素数で書き出す（例: 見た目 126×195 の図なら 252×390 ピクセル）。拡大しても印刷しても文字がつぶれない。資料に貼るときは表示幅を実寸の半分に指定すると、意図した大きさで鮮明に出る。

ただし 120 万画素を超える図は、縦横の比を保ったままそこまで縮めて書き出す（縦に十数段以上つながる図が目安。ラベルが長いほど早く届く）。画像は縮小されずにそのまま読み込まれるため、上限を置かないと 1 枚が大きすぎて ReadImage で開けなくなり、同時に開こうとした他の画像まで巻き添えで落ちる。長い図は縦に切って複数枚にすると、1 枚あたりが小さくなって鮮明さも保てる。

失敗した図は、エラー本文・行番号・その行の中身が返る。その行を直して呼び直す。

よくある失敗

ラベルの中に括弧・角括弧・波括弧をそのまま書くと落ちる。引用符で囲めば通る。

A[設定を読む (config.yaml)]      ← 落ちる
A["設定を読む (config.yaml)"]    ← 通る

これが最も多い原因。他に、日本語・長いラベル・多層のフローチャート・シーケンス図・クラス図・ガントは問題なく描画される（実測）。

HTML を書くときの注意

生成する HTML に CDN の <script src="...mermaid..."> を書かないこと。読み込むバージョンによって通る構文が変わるうえ、閲覧側に通信できない環境だと図がまったく出ない。

最初から書かず、このツールに差し替えさせる。 検査したバージョンと画面に出るものが同じになり、図のための通信は要らなくなる。書いてしまった読み込みはツールが消さないので、要らないと判断したら自分で消す（残っていても図の表示には影響しない）。

制限

1 回に扱える図は 30 個まで。1 図あたり 20,000 文字まで
1 回の呼び出し全体で 60 秒まで。1 つの図が時間切れになった時点で残りは打ち切る（描画が止まったページは待っても戻らない）
書き込みが許されていないタスクでは使えない（画像を保存できないため）
readonly/ 配下のファイルは書き換えない。検査だけしたい場合は embed: false を付けて呼ぶ
描画にはブラウザを使うため、1 回あたり数秒かかる。図ごとに呼び分けず、ファイル単位でまとめて呼ぶ方が速い

5.2 KiB Raw Blame History Unescape Escape