mermaid-visualizer

Mermaid ビジュアライザー

概要

テキストコンテンツを、プレゼンテーションやドキュメントに最適な、見やすくプロフェッショナルな Mermaid 図に変換します。よくある構文上の問題（リスト構文の競合、サブグラフの命名、スペースの問題）を自動的に処理し、Obsidian、GitHub、その他の Mermaid 対応プラットフォームで図が正しく描画されるようにします。

クイックスタート

Mermaid 図を作成するときは、次の手順に従います。

1. コンテンツを分析する - 主要な概念、関係性、流れを特定します
2. 図の種類を選ぶ - 最適な可視化方法を選択します（以下の「図の種類」を参照）
3. 設定を選択する - レイアウト、詳細度、スタイルを決定します
4. 図を生成する - 構文的に正しい Mermaid コードを作成します
5. Markdown 形式で出力する - 必要に応じて説明を添え、適切なコードフェンスで囲みます

デフォルトの前提：

• 横方向が指定されていない限り、縦方向のレイアウト（TB）
• 中程度の詳細度（シンプルさと情報量のバランスを取ります）
• 意味に応じた色を使ったプロフェッショナルな配色
• Obsidian／GitHub 互換の構文

図の種類

1. プロセスフロー（graph TB/LR）

最適な用途： ワークフロー、意思決定ツリー、逐次的なプロセス、AI エージェントのアーキテクチャ

使用する場面： コンテンツが手順、段階、または一連のアクションを説明している場合

主な特徴：

• サブグラフを使って関連する手順をグループ化するスイムレーン
• 遷移を示す矢印ラベル
• フィードバックループと分岐
• 色分けされた段階

設定オプション：

• layout: "vertical"（TB）、「horizontal」（LR）
• detail: "simple"（主要な手順のみ）、「standard」（説明付き）、「detailed」（注釈付き）
• style: "minimal"、「professional」、「colorful」

2. 循環フロー（円形レイアウトの graph TD）

最適な用途： 循環プロセス、継続的改善のループ、エージェントのフィードバックシステム

使用する場面： コンテンツが反復、フィードバック、または循環的な関係性を重視している場合

主な特徴：

• 要素が放射状に広がる中心ハブ
• 曲線のフィードバック矢印
• 明確なサイクルの表示

3. 比較図（並行経路を持つ graph TB）

最適な用途： 変更前後の比較、A 対 B の分析、従来型システムと最新システムの比較

使用する場面： コンテンツが 2 つ以上のアプローチやシステムを対比している場合

主な特徴：

• 並列レイアウト
• 中央の比較ノード
• 色やスタイルによる明確な区別

4. マインドマップ

最適な用途： 階層的な概念、知識の整理、トピックの細分化

使用する場面： コンテンツが明確な親子関係を持つ階層構造である場合

主な特徴：

• 放射状のツリー構造
• 複数階層のネスト
• 明確な視覚的階層

5. シーケンス図

最適な用途： コンポーネント間のやり取り、API 呼び出し、メッセージの流れ

使用する場面： コンテンツが、アクターやシステム間で時間とともに行われる通信を扱う場合

主な特徴：

• タイムラインベースのレイアウト
• アクターの明確な区分
• プロセスを示すアクティベーションボックス

6. 状態図

最適な用途： システムの状態、ステータスの遷移、ライフサイクルの段階

使用する場面： コンテンツが状態とその間の遷移を説明している場合

主な特徴：

• 明確な状態ノード
• ラベル付きの遷移
• 開始状態と終了状態

重要な構文ルール

解析エラーを防ぐため、次のルールを必ず守ってください。

ルール 1：リスト構文との競合を避ける

❌ WRONG: [1. Perception]       → Triggers "Unsupported markdown: list"
✅ RIGHT: [1.Perception]         → Remove space after period
✅ RIGHT: [① Perception]         → Use circled numbers (①②③④⑤⑥⑦⑧⑨⑩)
✅ RIGHT: [(1) Perception]       → Use parentheses
✅ RIGHT: [Step 1: Perception]   → Use "Step" prefix

ルール 2：サブグラフの命名

❌ WRONG: subgraph AI Agent Core  → Space in name without quotes
✅ RIGHT: subgraph agent["AI Agent Core"]  → Use ID with display name
✅ RIGHT: subgraph agent          → Use simple ID only

ルール 3：ノードの参照

❌ WRONG: Title --> AI Agent Core  → Reference display name directly
✅ RIGHT: Title --> agent          → Reference subgraph ID

ルール 4：ノードテキスト内の特殊文字

✅ Use quotes for text with spaces: ["Text with spaces"]
✅ Escape or avoid: quotation marks → use 『』instead
✅ Escape or avoid: parentheses → use 「」instead
✅ Line breaks in circle nodes only: ((Text<br/>Break))

ルール 5：矢印の種類

• --> 実線の矢印
• -.-> 破線の矢印（サポートシステムや任意の経路に使用）
• ==> 太い矢印（強調に使用）
• ~~~ 非表示のリンク（レイアウトのみ）

構文の完全なリファレンスと特殊なケースについては、references/syntax-rules.md を参照してください

設定オプション

すべての図で、次のパラメーターを指定できます。

レイアウト：

• direction：「vertical」（TB）、「horizontal」（LR）、「right-to-left」（RL）、「bottom-to-top」（BT）
• aspect：「portrait」（デフォルト）、「landscape」（横長）、「square」

詳細レベル：

• simple：主要な要素のみ。ラベルは最小限です
• standard：重要な説明を含む、バランスの取れた詳細度（デフォルト）
• detailed：注釈、説明、メタデータをすべて含みます
• presentation：スライド向けに最適化します（文字を大きくし、詳細を減らします）

スタイル：

• minimal：モノクロ、すっきりした線
• professional：意味に応じた色、明確な階層（デフォルト）
• colorful：鮮やかな色、高いコントラスト
• academic：論文やドキュメント向けのフォーマルなスタイル

追加オプション：

• show_legend：true/false - 色や記号の凡例を含めます
• numbered：true/false - ステップに連番を追加します
• title：文字列 - 図のタイトルを追加します

使用例のパターン

パターン 1：基本的なリクエスト

User: "Visualize the software development lifecycle"
Response: [Analyze → Choose graph TB → Generate with standard detail]

パターン 2：設定を指定

User: "Create a horizontal flowchart of our sales process with lots of detail"
Response: [Analyze → Choose graph LR → Generate with detailed level]

パターン 3：比較

User: "Compare traditional AI vs AI agents"
Response: [Analyze → Choose comparison layout → Generate with contrasting styles]

ワークフロー

1. 内容を理解する

   • 主な概念、エンティティ、関係性を特定します
   • 階層や順序を判断します
   • 比較や対比があれば確認します

2. 図の種類を選択する

   • 内容の構造に合った図の種類を選びます
   • ユーザーが図を使用する場面を考慮します
   • 判断が難しい場合は、プロセスフローをデフォルトとして使用します

3. 設定を選択する

   • ユーザーが指定したオプションを適用します
   • 指定されていないオプションには適切なデフォルトを使用します
   • 読みやすさを最適化します

4. Mermaid コードを生成する

   • すべての構文規則を厳密に守ります
   • 意味が分かる名前（説明的な ID）を使用します
   • 一貫したスタイルを適用します
   • よくあるエラーがないか確認します：
     • ノードテキストに「数字. 空白」のパターンがない
     • すべてのサブグラフが ID["表示名"] 形式になっている
     • すべてのノード参照で表示名ではなく ID を使用している

5. コンテキストを添えて出力する

   • 図の構造を簡潔に説明します
   • レンダリング互換性（Obsidian、GitHub など）に触れます
   • 調整や別バージョンの作成を提案します

デフォルトの配色

標準的なプロフェッショナル向けパレット：

• 緑（#d3f9d8/#2f9e44）：入力、知覚、開始状態
• 赤（#ffe3e3/#c92a2a）：計画、判断ポイント
• 紫（#e5dbff/#5f3dc4）：処理、推論
• オレンジ（#ffe8cc/#d9480f）：アクション、ツールの使用
• シアン（#c5f6fa/#0c8599）：出力、実行、結果
• 黄色（#fff4e6/#e67700）：ストレージ、メモリ、データ
• ピンク（#f3d9fa/#862e9c）：学習、最適化
• 青（#e7f5ff/#1971c2）：メタデータ、定義、タイトル
• グレー（#f8f9fa/#868e96）：中立的な要素、従来型のシステム

よくあるパターン

スイムレーンパターン（グループ化）

graph TB
    subgraph core["Core Process"]
        A --> B --> C
    end
    subgraph support["Supporting Systems"]
        D
        E
    end
    core -.-> support

フィードバックループパターン

graph TB
    A[Start] --> B[Process]
    B --> C[End]
    C -.->|Feedback| A

ハブ＆スポークパターン

graph TB
    Central[Hub]
    A[Spoke 1] --> Central
    B[Spoke 2] --> Central
    C[Spoke 3] --> Central

品質チェックリスト

出力前に、次の項目を確認します：

• ノードテキストに「数字. 空白」のパターンがない
• すべてのサブグラフで適切な ID 構文を使用している
• すべての矢印で正しい構文（-->, -.->）を使用している
• 色が一貫して適用されている
• レイアウトの方向が指定されている
• スタイル宣言がある
• 曖昧なノード参照がない
• Obsidian/GitHub のレンダラーと互換性がある
• ノードテキストに 絵文字がない - 代わりにテキストラベルや色分けを使用する

参考資料

詳細な構文規則とトラブルシューティングについては、次を参照してください：

• references/syntax-rules.md - 構文の完全なリファレンスとエラー防止策