AI生成Mermaid図が表示されない5つの原因と対処
この記事で学べること
- AI生成Mermaid図で起きた5つの描画問題と原因
- 特殊文字、矢印、長いラベル、日本語、入れ子構造を直す方法
- 構文だけで完了とせず、ブラウザ上の描画まで確認する手順
Mermaid図は生成後の描画確認まで行う
AIにMermaid図の作成を依頼したところ、記法が正しそうに見えても、ブラウザでは意図どおりに表示されないことがありました。Mermaidは、テキストで書いた記法からフローチャートなどを描くツールです。
このサイトで確認したのは、特殊文字、矢印の向き、長いラベル、日本語、入れ子構造の5種類の問題です。それぞれの症状と修正方法をたどることで、図が表示されない場合と、表示されても意味や配置が違う場合を分けて確認できます。
Mermaid図を5つの観点で検証する
私は、MarkdownファイルにMermaid記法を書いて、ドキュメントへ図を入れています。Markdownでは、#を見出し、-を箇条書きに使い、文章の区切りや項目を表せます。Mermaid記法を図として表示するには、その記法を読み取って描く環境も必要です。
以下は、2026年6月22日時点のこのサイトで確認した問題と対処です。Mermaidのバージョンや描画環境によって挙動が変わるため、別の環境で同じ問題や修正結果が出るとは限りません。
括弧・特殊文字を含む文字列が壊れる
括弧や特殊文字はMermaid構文と衝突する
図の中の箱や点をノードと呼び、そこに表示する文字列をラベルと呼びます。ラベルへ(optional)やAPI / SDKのような括弧・記号を入れた際、図が表示されなくなりました。ノードの書き方やMermaidのバージョンによっては、一部の記号がラベルの文字ではなく、構文の一部として扱われます。
文字列を引用符で囲んで構文衝突を防ぐ
ラベルを["テキスト"]のように引用符で囲むと、内部を文字列として扱いやすくなります。AIへの依頼に「特殊文字を含むラベルは引用符で囲む」と添えるか、生成された記法を確認して修正します。
ノード間の矢印の向きが意図と逆になる
矢印記号とノードの定義順で向きが逆になる
処理の流れを示す図で、矢印の向きが意図と逆になっていました。「AがBを呼び出す」という関係を示したいのに、「BがAを呼び出す」と読める図になっていた例です。
Mermaidは矢印記号の始点と終点を構文どおりに描画する
Mermaidは書かれた矢印の向きを描きます。AIへ渡した関係の説明が曖昧だと、図として表示できる記法でも、呼び出す側と呼び出される側が入れ替わることがあります。
矢印の始点と終点を描画結果で確認する
依頼時には「AからBへ」と方向を示します。生成後も図を開いて始点と終点を確かめ、意図と逆ならA --> BとB --> Aを入れ替えます。構文が通るかと、関係を正しく表すかは、別々に確認する必要があります。
ラベルが長すぎてレイアウトが崩れる
長いラベルはノード幅と折り返しを崩す
ノードのラベルへ詳しい説明を入れると、図が横に広がりすぎて読みにくくなりました。
ラベルを短くし、詳しい説明を本文へ移す
私はラベルを短くし、補足を図の外の文章へ移しました。AIへ「ノードのラベルは10〜15文字程度」と指定すると、コンパクトな図を作りやすくなります。
日本語テキストで表示が崩れる
日本語フォントと改行で表示が崩れる
日本語のラベルで、一部の文字が正しく表示されないことがありました。日本語の表示は、使っている環境や図を描く仕組みによって異なる場合があります。
日本語ラベルを短くして描画環境を確認する
まず、使用中のMermaidのバージョンと描画環境で、日本語を表示できるか確認します。問題が再現する場合、私はラベルを英語に変え、日本語の説明を図の外へ移しました。AIに英語のラベルを指定する方法は、このときの回避策です。
入れ子構造が正しく解釈されない
subgraphの境界と接続が意図と異なる
subgraphは、関連するノードを一つのグループにまとめる記法です。グループの中に別のグループを置いた際、内側に入るはずのノードが外へ出たり、グループが重複して表示されたりしました。
Mermaidは入れ子の境界と接続先を構文から解釈する
グループの範囲はsubgraphとendで定義します。インデントを整えるとコードは読みやすくなりますが、ノードの所属はその二つの記法で確認します。図を表示できても、境界が意図と一致するとは限りません。
入れ子の階層と接続先を分けて定義する
生成した記法をMermaidのオンラインエディタやプレビューで開き、所属が違う場合はendの位置を確認して修正します。複雑な入れ子では、最初に単純な構造だけを作り、段階的に追加すると、どこで所属が変わったかを確認しやすくなります。
まとめ：Mermaid図は5項目を実画面で確認して完成とする
Mermaid図では、表示できること、関係を正しく表すこと、読みやすいことを分けて確認すると、問題を切り分けられます。構文検査で止まらず、実際の画面で矢印の向きやノードの所属、文字の表示まで確かめる必要があります。
修正結果は、Mermaidの版、図を描くソフトウェア、フォント、文字や配置の設定にも左右されます。このサイトで使えた対処も、別の環境では表示を確認してから採用するのが判断の前提になります。