Mermaid Diagramming

Create professional software diagrams using Mermaid's text-based syntax.

Core Syntax Structure

All Mermaid diagrams follow this pattern:

diagramType
  definition content

Key principles:

• First line declares diagram type (e.g., classDiagram, sequenceDiagram, flowchart)
• Use %% for comments
• Whitespace aids readability; not required
• Typos break diagrams silently -- validate in Mermaid Live

Diagram Type Selection Guide

Default to flowchart when the user's intent is unclear. Flowcharts cover the widest range of use cases.

Class Diagram

classDiagram
    Title -- Genre
    Title *-- Season
    Title *-- Review
    User --> Review : creates

    class Title {
        +string name
        +int releaseYear
        +play()
    }

    class Genre {
        +string name
        +getTopTitles()
    }

Sequence Diagram

sequenceDiagram
    participant User
    participant API
    participant Database

    User->>API: POST /login
    API->>Database: Query credentials
    Database-->>API: Return user data
    alt Valid credentials
        API-->>User: 200 OK + JWT token
    else Invalid credentials
        API-->>User: 401 Unauthorized
    end

Flowchart

flowchart TD
    Start([User visits site]) --> Auth{Authenticated?}
    Auth -->|No| Login[Show login page]
    Auth -->|Yes| Dashboard[Show dashboard]
    Login --> Creds[Enter credentials]
    Creds --> Validate{Valid?}
    Validate -->|Yes| Dashboard
    Validate -->|No| Error[Show error]
    Error --> Login

ERD

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : includes

    USER {
        int id PK
        string email UK
        string name
        datetime created_at
    }

    ORDER {
        int id PK
        int user_id FK
        decimal total
        datetime created_at
    }

State Diagram

stateDiagram-v2
    [*] --> Draft
    Draft --> Submitted : submit
    Draft --> Cancelled : cancel
    Submitted --> Processing : approve
    Processing --> Shipped : ship
    Shipped --> Delivered : confirm
    Delivered --> [*]
    Cancelled --> [*]

Detailed References

• references/class-diagrams.md - Domain modelling, relationships (association, composition, aggregation, inheritance), multiplicity, methods/properties
• references/sequence-diagrams.md - Actors, participants, messages (sync/async), activations, loops, alt/opt/par blocks, notes
• references/flowcharts-basic.md - Node shapes, connections, subgraphs
• references/flowcharts-advanced.md - Styling, comprehensive examples, patterns
• references/erd-basic.md - Entities, relationships, cardinality, attributes
• references/erd-patterns.md - Schema examples, design patterns
• references/c4-diagrams.md - System context, container, component diagrams, boundaries
• references/advanced-features.md - Configuration, layout, export options
• references/theming.md - Themes, colours, visual styling
• references/other-diagrams.md - State diagrams, git graphs, gantt charts, pie/quadrant

Best Practices

1. Draft core entities first - Add 3-5 main nodes, then connect. Add attributes and detail in a second pass.
2. Label every node and edge - Unlabelled arrows force readers to guess the relationship.
3. Add %% comments above complex sections - Explain why, not what. Future editors read comments before syntax.
4. Split at 15 nodes - Diagrams with more than 15 nodes lose clarity. Break into focused views linked by a parent diagram.
5. Store .mmd files next to the code they describe - Keep diagrams and source in the same PR so they stay in sync.
6. Set a title on every diagram - Use the title keyword or a Markdown heading directly above the code block.
7. Test in Mermaid Live before committing - Paste the diagram into mermaid.live to catch silent failures.
8. Check colour contrast - Verify foreground/background pairs meet WCAG AA (4.5:1 ratio). Do not rely on colour alone to convey meaning.

Validation Loop (Required)

Every diagram passes through this generate-validate-repair cycle before output.

Step 1: Generate

Write the diagram using strict Mermaid syntax. Apply these rules during generation:

Step 2: Validate

Self-check the generated diagram against these failure patterns:

1. Scan all node labels for unescaped special characters: ( ) { } $ % & < > #
2. Check for bare end used as a node name or label (not as a block closer)
3. Verify arrow syntax matches the diagram type (e.g., --> for flowchart, ->> for sequence)
4. Confirm diagram type keyword is spelled correctly on line 1
5. Check participant/actor names for spaces (wrap in quotes if present)

If any issue is found, fix it before output. Do not ask the user to fix syntax.

Step 3: Render verification

After outputting the diagram, recommend the user verify rendering:

• Quick check: paste into Mermaid Live
• CLI validation: npx @mermaid-js/mermaid-cli -i diagram.mmd -o test.png
• MCP tools: if a Mermaid MCP server is available, use it for in-session validation

Step 4: Repair (if rendering fails)

If the user reports a rendering failure:

1. Read the error message (if available) and identify the failing line
2. Check the syntax rules table above for the matching pattern
3. Fix and re-output the corrected diagram
4. Never output the same broken syntax twice

Configuration and Theming

Configure diagrams using frontmatter:

---
config:
  theme: base
  themeVariables:
    primaryColor: "#ff6b6b"
---
flowchart LR
    A --> B

Themes (default to default; use base for full colour control):

Layout: Default to dagre. Switch to elk when dagre produces crossed lines on 20+ node diagrams.

Look: Default to classic. Use handDrawn for informal docs or whiteboard-style presentations.

Exporting and Rendering

Platform support:

Export commands:

• Online: Mermaid Live Editor with PNG/SVG export
• CLI: mmdc -i input.mmd -o output.png (install via npm install -g @mermaid-js/mermaid-cli)
• Docker: docker run --rm -v $(pwd):/data minlag/mermaid-cli -i /data/input.mmd -o /data/output.png

Common Pitfalls

Syntax failures (most frequent):

• Unescaped special characters - Parentheses, brackets, $, % in node labels crash the parser. Always quote labels containing these characters.
• Reserved word end - Using end as a node name breaks diagrams silently. Wrap in quotes or rename.
• Misspelled diagram types - classDiagram not classdiagram. Case matters for the type keyword.
• Wrong arrow syntax - Each diagram type uses different arrows. Flowcharts use -->, sequence uses ->>, class uses ..>.

Platform-specific failures:

• GitHub Wiki - Mermaid rendering is broken despite documentation claiming support. Use README or Pages instead.
• Azure DevOps - Requires ::: mermaid syntax, not standard backtick fences.
• Obsidian iOS - Mermaid fails to render entirely on iOS. Desktop works.
• C4 diagrams on GitHub - C4 is experimental in Mermaid. Renders in mermaid.live but often fails on GitHub.

Structural issues:

• Overcomplexity - Split diagrams with more than 15 nodes into multiple focused views.
• Nested subgraphs - Deep nesting fails on some platforms. Keep to 2 levels maximum.