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

Type	When to use	Reference
Class Diagram	Domain modelling, OOP design, entity relationships	references/class-diagrams.md
Sequence Diagram	API flows, authentication, component interactions	references/sequence-diagrams.md
Flowchart	Processes, algorithms, decision trees, user journeys	references/flowcharts-basic.md, references/flowcharts-advanced.md
ERD	Database schemas, table relationships, data modelling	references/erd-basic.md, references/erd-patterns.md
C4 Diagram	Software architecture at Context, Container, Component levels	references/c4-diagrams.md
State Diagram	State machines, lifecycle states, workflow status	references/other-diagrams.md
Git Graph	Branching strategies, commit history	references/other-diagrams.md
Gantt Chart	Project timelines, scheduling, sprint planning	references/other-diagrams.md
Pie/Quadrant	Data distribution, prioritisation matrices	references/other-diagrams.md

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:

Rule	Wrong	Correct	Why
Escape parentheses in labels	node[Node (example)]	node["Node (example)"]	Bare parentheses crash the parser
Quote text with special characters	A[Price: $100]	A["Price: $100"]	$, %, &, <, > break parsing
Quote the reserved word end	A --> end	A --> End["end"]	Unquoted end silently breaks diagrams
Use HTML entities when quotes fail	A["alert()"]	A["alert&lpar;&rpar;"]	Nested parens inside quotes still fail
Avoid {} in comments	%% config: {dark}	%% config dark theme	Curly braces in comments break parsing
Use unique node IDs	Reusing A across subgraphs	A1, A2 for distinct nodes	Duplicate IDs cause silent overwrites

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):

Theme	When to use
default	General-purpose diagrams (recommended)
forest	Green earth tones for environmental or organic topics
dark	Dark-mode pages or presentations
neutral	Grayscale professional documentation
base	Full colour customisation via themeVariables

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:

Platform	Status	Notes
GitHub README/Issues	Works	Wiki rendering broken. C4 diagrams often fail.
GitLab	Works	May need cache refresh after adding new diagrams.
VS Code	Works	Requires Markdown Mermaid extension.
Obsidian	Partial	Desktop works. iOS fails entirely. Pie charts render as empty boxes.
Azure DevOps	Works	Requires ::: mermaid syntax, not backtick fences.
PDF export	Fails	Export as PNG/SVG from mermaid.live first.

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.