AI生成Mermaid図が表示されない5つの原因と対処
この記事で学べること
- AI生成Mermaid図で起きた5つの描画問題と原因
- 特殊文字、矢印、長いラベル、日本語、入れ子構造を直す方法
- 構文だけで完了とせず、ブラウザ上の描画まで確認する手順
Mermaid図は生成後の描画確認まで行う
AIで作成したMermaid（テキスト記法から生成する図）は、構文が正しそうに見えても、特殊文字、矢印、長いラベル、日本語、入れ子構造によって意図どおり描画されない場合があります。このサイトでも、記法の出力完了とブラウザでの表示完了が一致しないケースを確認しました。公開前には、構文検査だけでなく実際の描画結果まで確認します。
この記事では、「構文が正しそうなMermaid図が表示されないとき、どこから確認すべきか」という問いに焦点を当て、期待と結果の差、確認できた条件、再発を防ぐ判断を扱います。
最後まで読むと、「構文が正しそうなMermaid図が表示されないとき、どこから確認すべきか」という問いを、自分の状況に照らして判断するための材料を持ち帰れます。
Mermaid図を5つの観点で検証する
Mermaidは、テキストで記述するとフローチャートやシーケンス図などを自動生成してくれるツールです。MarkdownファイルにMermaid記法を書くだけで図が表示されるため、ドキュメントに図を入れる手段として使っています。
AI支援でMermaid記法を作成すると、多くの場合は正しく動きますが、特定のパターンで図が正しく表示されないことがありました。この記事では、実際に発生した5つのパターンと対処方法を記録します。Mermaidの構文やレンダリング挙動はバージョンと描画環境で変わるため、2026年6月22日時点のこのサイトで確認した範囲として扱います。
括弧・特殊文字を含む文字列が壊れる
括弧や特殊文字はMermaid構文と衝突する
ノードのラベルに括弧や記号（例：(optional) や API / SDK）を含めたところ、図が表示されなくなりました。一部の記号は、ノード記法やMermaidのバージョンによって構文として解釈されることがあります。
文字列を引用符で囲んで構文衝突を防ぐ
ラベルを引用符で囲みます。Mermaid記法では、ラベルを ["テキスト"] の形式で書くと、内部の文字列をラベルとして扱いやすくなります。AIに依頼する際は「特殊文字を含む場合は引用符で囲んでください」と明示するか、生成後に確認して修正します。
ノード間の矢印の向きが意図と逆になる
矢印記号とノードの定義順で向きが逆になる
処理の流れを表すフローチャートを作成したとき、矢印の向きが逆になっているノードが複数ありました。「AがBを呼び出す」という関係が「BがAを呼び出す」のように表示されていました。
Mermaidは矢印記号の始点と終点を構文どおりに描画する
AIは記法の構文は正しく書けますが、「どちらがどちらを呼び出すか」という関係の方向性は、説明が曖昧だと逆に解釈されることがあります。
矢印の始点と終点を描画結果で確認する
依頼時に矢印の方向を「AからBへ」という形で明示します。また、生成された図を表示して確認し、方向が逆のものを個別に修正します。修正は記法の A --> B を B --> A に変えるだけなので、確認後に直す手順を取っています。
ラベルが長すぎてレイアウトが崩れる
長いラベルはノード幅と折り返しを崩す
ノードのラベルに詳しい説明を入れようとして長い文章を書いたところ、図全体のレイアウトが横に広がりすぎて読みにくくなりました。
ラベルを短くし、詳しい説明を本文へ移す
ノードのラベルは短く、補足は図の外のテキストに書くようにしました。AIへの依頼時に「ノードのラベルは10〜15文字程度にしてください」と指定すると、コンパクトな図が生成されやすくなります。
日本語テキストで表示が崩れる
日本語フォントと改行で表示が崩れる
日本語のラベルを含むMermaid図で、一部の文字が正しく表示されないことがありました。特定の環境や描画エンジンによって、日本語の扱いに差がある場合があります。
日本語ラベルを短くして描画環境を確認する
まず、使用しているMermaidのバージョンと描画環境で日本語が動作するかを確認します。問題が再現する場合は、ラベルを英語に変えて日本語の説明を図の外に書く方法に切り替えました。AIに「ラベルは英語で書いてください」と指定することで、この問題を回避できます。
入れ子構造が正しく解釈されない
subgraphの境界と接続が意図と異なる
サブグラフ（グループ）を使って関連するノードをまとめようとしたとき、入れ子のグループが期待した構造にならないことがありました。外側のグループに入るべきノードが外に出てしまう、またはグループが重複して表示されるケースがありました。
Mermaidは入れ子の境界と接続先を構文から解釈する
Mermaidのサブグラフ記法は、subgraph と end の構造で定義されます。インデントは可読性に影響しますが、所属関係そのものは構文で確認します。AIが生成するコードは構文としては正しくても、グループの境界が意図と異なることがあります。
入れ子の階層と接続先を分けて定義する
入れ子構造を使う場合は、生成されたコードを一度MermaidのオンラインエディタやLiveのプレビューで確認します。問題があれば、サブグラフの end の位置を修正します。複雑な入れ子が必要な場合は、最初に構造だけをシンプルに書いてもらい、段階的に追加していく方法が確認しやすいです。
まとめ：Mermaid図は5項目を実画面で確認して完成とする
AIが作ったMermaid図は、細かな制約の組み合わせで崩れます。特殊文字、関係の方向、文字量、フォント、CSS、レンダラー、ライブラリの版、入れ子の境界を分けて確認します。
生成後にプレビューで確認し、パターンに合わせた修正手順を持っておくと、対処の時間を短縮できます。
最初に問題の図をブラウザで開き、特殊文字、矢印、ラベル、日本語、入れ子構造のどこで崩れているかを1項目ずつ切り分けます。描画結果はレンダラー、ライブラリの版、フォント、CSSにも左右されるため、別環境で同じ結果になるとは限りません。