Mermaid Diagrams

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: costa-marcello
• Source: costa-marcello/skillkit
• License: MIT

Install and usage instructions live in the source repository linked above.