Mermaid Diagram

Use this skill to produce Mermaid diagrams that render cleanly in Markdown, documentation, Obsidian, GitHub, and similar tools.

When To Use

• Convert a process, architecture, decision path, timeline, or data relationship into Mermaid.
• Repair an existing Mermaid diagram that fails to render.
• Choose the right diagram type for an explanation.
• Simplify a dense written explanation into a readable visual structure.

Default Workflow

1. Clarify the user's goal and intended reader.
2. Choose the smallest diagram type that explains the idea clearly.
3. Draft valid Mermaid code.
4. Check the syntax rules below before finalizing.
5. If the diagram is complex, prefer two small diagrams over one crowded diagram.

Diagram Type Selection

• flowchart: workflows, decisions, systems, pipelines, cause-effect paths.
• sequenceDiagram: conversations, API calls, handoffs, time-ordered interactions.
• classDiagram: object models, interfaces, inheritance, module relationships.
• stateDiagram-v2: state machines, lifecycle transitions, app or order states.
• erDiagram: database entities and relationships.
• gantt: schedules and delivery plans.
• mindmap: topic breakdowns and idea trees.

Critical Mermaid Rules

Quote Labels With Special Characters

Labels containing :, (), [], {}, @, ;, or , should be wrapped in double quotes.

flowchart LR
    A["Function: process(input)"]
    B["Array [1, 2, 3]"]
    A --> B

Avoid Lowercase end As A Node Id

end is a reserved word in flowcharts. Use End, END, or another id.

flowchart TD
    Start --> End

Give Every Subgraph An Id

Use subgraph ID["Title"], not only subgraph "Title".

flowchart TD
    subgraph AUTH["Authentication"]
        A["Login"]
        B["Check session"]
    end
    A --> B

Use Note Only In Sequence Diagrams

Note right of A: is valid in sequenceDiagram, but not in flowchart.

sequenceDiagram
    participant User
    participant API
    User->>API: Request
    Note right of API: Validate input

For flowcharts, use a normal node instead:

flowchart TD
    A["Request"]
    N["Note: validate input"]
    A --> N

Define Classes Before Linking Them

In classDiagram, define referenced classes before relationships.

classDiagram
    class Animal {
        +String name
        +makeSound()
    }
    class Dog {
        +bark()
    }
    Animal <|-- Dog

Starter Examples

Flowchart

flowchart TD
    Start["Start"]
    Check{"Valid input?"}
    Fix["Ask for correction"]
    Done["Done"]

    Start --> Check
    Check -->|Yes| Done
    Check -->|No| Fix
    Fix --> Check

Sequence Diagram

sequenceDiagram
    participant User
    participant App
    participant API

    User->>App: Submit form
    App->>API: Send request
    API-->>App: Return result
    App-->>User: Show status

Entity Relationship

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ ORDER_ITEM : contains

    CUSTOMER {
        string id
        string name
    }
    ORDER {
        string id
        date created_at
    }

Validation Checklist

Before returning a diagram:

• The first line declares a valid Mermaid diagram type.
• Labels with special characters are quoted.
• Flowchart subgraphs use subgraph ID["Title"].
• No node id is lowercase end.
• Note appears only inside sequenceDiagram.
• Class diagrams define classes before relationships.
• The diagram is readable enough for the intended audience.

For common parse errors and fixes, read references/common-errors.md when needed.