mcpField
M
mermaid-syntax

mermaid-syntax

github.com/awesome-skillsドキュメント23398 回インストール44 週間前に更新
リポジトリ

mermaid-syntax について

mermaid-syntax は、正しい Mermaid 図を記述するためのリファレンススキルです。複数の図の構文、パーサーの注意点、作成後のチェック項目をまとめています。

主な機能

  1. 01複数の図形式の構文ガイド
  2. 02特殊文字のエスケープ規則
  3. 03予約語と識別子の注意点
  4. 04Mermaid v11 の動作に関する説明
  5. 05作成後の検証チェックリスト

活用シーン

  1. 01Mermaid 図の構文エラーを減らす
  2. 02描画前にラベルと識別子を確認する
  3. 03バージョン固有の注意点を調べる

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/awesome-skills/mermaid-syntax-skill --skill mermaid-syntax

インストール後、Claude Code で/mermaid-syntaxを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

README.md
examples/
sequence-examples.md
flowchart-examples.md
references/
flowchart-complete.md
class-state-complete.md
sequence-complete.md
other-diagrams.md
scripts/
validate-mermaid.sh

詳細

Mermaid 図の構文ガイド

エラーのない Mermaid 図を生成するための包括的な構文リファレンスです。よくある間違いを防ぎ、フローチャート、シーケンス図、クラス図、状態遷移図、ER 図、ガントチャートなど、Mermaid v11 の機能に対応しています。

図のテスト先： https://mermaid.live/

graph よりも flowchart を推奨： どちらも動作しますが、flowchart は機能のサポートが充実した最新の構文です。

重要なルール（エラーの 90％ を防止）

1. 特殊文字のエスケープ

特殊文字を含むテキストは、必ず二重引用符で囲みます。

flowchart LR
    A["Text with (parentheses)"]
    B["Text with / or \ slashes"]
    C["Colon: in text"]

引用符が必要な文字： ( ) [ ] { } / \ : ; # @ ! ? < > " '

2. 予約語（「end」だけではありません！）

複数の予約語が図の表示を妨げます。安全な ID と引用符付きラベルを使用してください。

flowchart LR
    node1["end"]           %% Safe: quoted with different ID
    node2["default"]       %% Safe: "default" is also reserved
    node3["End"]           %% Safe: capitalized

すべての予約語（引用符付きラベルを使用）：

  • end、default
  • style、linkStyle、classDef、class
  • call、href、click、interpolate

パターン： reserved[text] ではなく、safeId["reserved word text"] を使用します。

3. ノード ID の先頭文字

o または x で始まるノードは、意図しないエッジの種類を作成します。

flowchart LR
    orderNode[Order]    %% Good: full word
    oNode[O-Node]       %% Bad: might create circle edge

解決策： 説明的な ID を使用し、先頭が o または x の 1 文字だけの ID は避けてください。

4. セミコロンの HTML エンティティコード

シーケンス図では、セミコロンは改行を表します。リテラルのセミコロンには #59; を使用してください。

sequenceDiagram
    A->>B: Value#59; Key#59; Data
5. コメントには %% を使用

単一の % は図の表示を妨げます。必ず %% を使用してください。

flowchart LR
    %% This is a valid comment
    A --> B
6. HTML タグを含むサブグラフ

<br/> を含むサブグラフのタイトルは、引用符で囲んでください。

flowchart TB
    subgraph "Title with<br/>line break"
        A --> B
    end
7. スタイルプロパティのエスケープ

stroke-dasharray のカンマはバックスラッシュでエスケープしてください。

flowchart LR
    A --> B
    linkStyle 0 stroke-dasharray: 5\,5
8. フロントマターは 1 行目に記述

フロントマターの --- は、1 行目の唯一の内容でなければなりません。

---
config:
  theme: forest
---
flowchart LR
    A --> B

誤り： --- の前に空白や内容があると、図の表示が妨げられます。

9. マインドマップの < 文字の不具合

マインドマップでは、< は &lt; として表示されます。代わりに言葉を使用してください。

mindmap
    root((Comparison))
        Less than 10    %% Instead of "< 10"
        Greater than 5  %% Instead of "> 5"
10. クラス図におけるコロンの制限

クラスのメンバー型にコロンを使う場合は注意が必要です。戻り値の型の構文を使用してください。

classDiagram
    class MyClass {
        +getData() Map~String, Object~
    }

注： コロンを含む複雑なジェネリック型は、正しく表示されない場合があります。

11. 入れ子のサブグラフをリンクする際の不具合

親サブグラフと入れ子のサブグラフの両方にリンクすると、構文エラーが発生します。

flowchart LR
    %% BAD: linking to both system AND sub-system breaks
    %% A --> system
    %% B --> sub-system

    %% GOOD: link to nodes inside, not subgraph itself
    A --> service1
    B --> service2

    subgraph system
        subgraph sub-system
            service1
            service2
        end
    end

回避策： サブグラフ ID 自体ではなく、サブグラフ内のノードにリンクしてください。

12. サブグラフの方向の継承

サブグラフのノードが外部にリンクされている場合、方向は無視され、親から継承されます。

flowchart LR
    A --> B
    subgraph sub [My Subgraph]
        direction TB  %% Ignored if C links outside!
        C --> D
    end
    B --> C  %% This external link forces LR direction

ルール： サブグラフの方向が機能するのは、すべてのノードがサブグラフ内にとどまる場合だけです。

13. v11 の矢印なしエッジの不具合（v11.0～11.4）

Mermaid v11.0～v11.4.x では、---（矢印のない線）の構文に不具合があり、矢印が表示されます。

flowchart LR
    %% BROKEN in v11.0-11.4: shows arrow instead of line
    A --- B

    %% Workaround: use explicit arrow and style
    C --> D
    linkStyle 0 stroke:#333,stroke-width:2px

修正方法： Mermaid v11.5.0 以降にアップグレードしてください。

14. v11 の Markdown がデフォルトになる破壊的変更

v11 では、v10 からの破壊的変更により、すべてのノードラベルがデフォルトで Markdown として表示されます。

flowchart LR
    %% v10: plain text, v11: renders as Markdown
    A[**bold** and _italic_]

    %% Problem: underscores in text become italic
    B["file_name_here"]  %% Use quotes to prevent issues

注： サポートされるのは太字（**）と斜体（_ または *）のみです。バッククォートによるインラインコードは機能しない場合があります。

15. 設定の制限（セキュア設定）

maxTextSize（デフォルト：50,000 文字）と maxEdges（デフォルト：500）はセキュア設定であり、フロントマターから設定することはできません。

---
config:
  maxTextSize: 100000  %% IGNORED! Secure setting
---
flowchart LR
    A --> B

回避策： 図の設定ではなく、JavaScript の mermaid.initialize() で設定してください。

16. linkStyle の最後の属性に 16 進カラーを指定する際の不具合

linkStyle の最後の属性に 16 進カラーを指定すると、解析エラーが発生します。

flowchart LR
    A --> B
    %% BAD: hex color as last attribute
    %% linkStyle 0 stroke-width:4px,stroke:#FF69B4

    %% GOOD: hex color NOT last, or use color name
    linkStyle 0 stroke:#FF69B4,stroke-width:4px
    %% OR: linkStyle 0 stroke-width:4px,stroke:hotpink

回避策： 16 進カラーをほかの属性より前に置くか、CSS の色名を使用してください。

17. クラス図の名前空間の制限

関係と注記は、名前空間ブロックの外側で定義しなければなりません。

classDiagram
    namespace MyPackage {
        class ClassA
        class ClassB
    }
    %% Relationships OUTSIDE namespace block
    ClassA --> ClassB
    note for ClassA "This note is outside namespace"

制限： 入れ子の名前空間はサポートされていません。フラットな構造を使用してください。

18. アーキテクチャ図のラベル文字

アーキテクチャ図のノードラベルで使用できるのは [a-zA-Z0-9_ ] のみです。ハイフンや特殊文字を使うと正しく表示されません。

architecture-beta
    %% BAD: service db[Cloud-Name]  (hyphen breaks)
    %% GOOD: use underscore or spaces
    service db(database)[Cloud_Name]

Mermaid v11 の新機能

手描き風の見た目
%%{init: {"look": "handDrawn"}}%%
flowchart LR
    A[Sketchy] --> B[Style]
双方向矢印（シーケンス図）
sequenceDiagram
    A <<->> B: Bidirectional
    A <<-->> B: Bidirectional dotted
設定ディレクティブ
%%{init: {
    "theme": "dark",
    "flowchart": {"curve": "linear"}
}}%%
flowchart LR
    A --> B

図の種類クイックリファレンス

フローチャートの方向
構文方向
flowchart TB上から下
flowchart TD上から下（TB と同じ）
flowchart BT下から上
flowchart LR左から右
flowchart RL右から左
ノードの形状
構文形状
A[text]長方形
A(text)角丸長方形
A([text])スタジアム形
A[[text]]サブルーチン
A[(text)]円柱（データベース）
A((text))円
A{text}ひし形
A{{text}}六角形
A>text]非対称
エッジの種類
構文種類
A --> B矢印
A --- B線（矢印なし）
A -.- B点線
A ==> B太い矢印
A -.-> B点線の矢印
A --text--> Bテキスト付き矢印
A -- text --- Bテキスト付き線
サブグラフの構文
flowchart TB
    subgraph GroupName["Display Title"]
        direction LR
        A --> B
    end
    C --> GroupName

シーケンス図の基本

メッセージの矢印の種類
構文説明
A->B実線、矢印なし
A-->B点線、矢印なし
A->>B実線、矢印あり
A-->>B点線、矢印あり
A-xB実線、終端がバツ印
A-)B実線、開いた矢印（非同期）
参加者の定義
sequenceDiagram
    participant A as Alice
    actor B as Bob
    A->>B: Hello
アクティベーション
sequenceDiagram
    A->>+B: Request
    B-->>-A: Response

または明示的に指定します。

sequenceDiagram
    A->>B: Request
    activate B
    B-->>A: Response
    deactivate B
制御フロー
sequenceDiagram
    alt Success
        A->>B: OK
    else Failure
        A->>B: Error
    end

    opt Optional
        A->>B: Maybe
    end

    loop Every minute
        A->>B: Ping
    end

    par Parallel
        A->>B: Task1
    and
        A->>C: Task2
    end
注記
sequenceDiagram
    Note right of A: Single line note
    Note over A,B: Spanning note

クラス図の基本

クラスの定義
classDiagram
    class Animal {
        +String name
        +int age
        +makeSound()
    }
可視性修飾子
記号意味
+パブリック
-プライベート
#保護
~パッケージ／内部
関係
構文意味
A <|-- B継承（B が A を拡張）
A *-- Bコンポジション
A o-- B集約
A --> B関連
A ..> B依存
A ..|> B実現
多重度
classDiagram
    Customer "1" --> "*" Order : places

状態図の基本

基本状態
stateDiagram-v2
    [*] --> State1
    State1 --> State2: transition
    State2 --> [*]
複合状態
stateDiagram-v2
    state Parent {
        [*] --> Child1
        Child1 --> Child2
    }
選択とフォーク
stateDiagram-v2
    state choice <<choice>>
    State1 --> choice
    choice --> State2: if condition
    choice --> State3: else

    state fork <<fork>>
    State4 --> fork
    fork --> State5
    fork --> State6

よくあるエラーパターン

エラー 1：特殊文字を引用符で囲んでいない
%% BAD - breaks parsing
A[Click here (optional)]
B[User: Admin]

%% GOOD - quoted text
A["Click here (optional)"]
B["User: Admin"]
エラー 2：予約語「end」
%% BAD - breaks diagram
A --> end
subgraph end

%% GOOD - quoted or capitalized
A --> End
A --> ["end"]
subgraph "End Phase"
エラー 3：シーケンス図のセミコロン
%% BAD - treated as line break
A->>B: key;value;data

%% GOOD - HTML entity
A->>B: key#59;value#59;data
エラー 4：引用符の入れ子
%% BAD - quote conflict
A["Say "Hello""]

%% GOOD - use single quotes inside
A["Say 'Hello'"]
%% Or use HTML entity
A["Say #quot;Hello#quot;"]
エラー 5：フローチャートでコロンを引用符で囲んでいない
%% BAD - colon breaks node text
A[Step 1: Initialize]

%% GOOD - quoted
A["Step 1: Initialize"]

その他の図の種類（クイックスタート）

ER 図
erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
ガントチャート
gantt
    title Project Timeline
    dateFormat YYYY-MM-DD
    section Phase 1
        Task A :a1, 2024-01-01, 30d
        Task B :after a1, 20d
円グラフ
pie title Distribution
    "A" : 40
    "B" : 30
    "C" : 30
Git グラフ
gitGraph
    commit
    branch develop
    commit
    checkout main
    merge develop

検証チェックリスト

Mermaid 図を完成させる前に、次の項目を確認してください。

  1. 特殊文字を含むテキストはすべて引用符で囲まれている
  2. 予約語をノード ID に使用していない（end、default、style、class など）
  3. 単独の o または x で始まるノード ID を使用していない
  4. シーケンスメッセージ内のセミコロンには #59; を使用している
  5. 入れ子になった引用符には単一引用符または HTML エンティティを使用している
  6. <br/> または特殊文字を含む場合、サブグラフのタイトルを引用符で囲んでいる
  7. 図の種類の宣言が正しい（flow-chart ではなく flowchart）
  8. コメントには %% を使用している（単独の % ではない）
  9. stroke-dasharray のカンマを \, でエスケープしている
  10. frontmatter の --- が最初の行にある（前に空白がない）
  11. マインドマップでは < 文字を避けている（単語を使用する）
  12. 親サブグラフと入れ子のサブグラフの両方にリンクしていない（代わりに内部のノードにリンクする）
  13. サブグラフの方向が確実に機能するのは、すべてのノードが内部にとどまる場合のみ
  14. ---（矢印なし）を使用する場合、Mermaid v11.5+ であることを確認するか、回避策を使用する
  15. ラベル内のアンダースコアは v11 で斜体として表示される場合がある（引用符を使用する）
  16. maxTextSize／maxEdges は frontmatter で設定できない（セキュリティ設定）
  17. linkStyle：16 進数カラーを最後の属性にしない（または色名を使用する）
  18. classDiagram：関係と注記は namespace ブロックの外に記述する
  19. architecture-beta：ラベルには [a-zA-Z0-9_ ] のみを使用し、ハイフンは使用しない
  20. コミットする前に https://mermaid.live/ でテストする

参考資料

参考ファイル

各図の種類の詳細な構文については、以下を参照してください。

  • references/flowchart-complete.md - 30 種類以上のノード形状、エッジのスタイル、サブグラフのネスト
  • references/sequence-complete.md - すべてのメッセージの種類、ボックス、ブレーク、クリティカルセクション
  • references/class-state-complete.md - クラスの注釈、状態の並行処理、ER 図、注記
  • references/other-diagrams.md - ガントチャート、円グラフ、Git グラフ、マインドマップ、タイムライン
サンプルファイル

examples/ にある動作するサンプル：

  • examples/flowchart-examples.md - よく使われるフローチャートのパターン
  • examples/sequence-examples.md - API フロー、認証フローのパターン
スクリプト
  • scripts/validate-mermaid.sh - 基本的な構文検証用ヘルパー
外部リソース

コメント

Markdown 対応