# 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 回あたり数秒かかる。図ごとに呼び分けず、ファイル単位でまとめて呼ぶ方が速い