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