Mermaid Generator

Generate valid, error-free Mermaid diagrams following strict syntax rules and best practices.

Core Principles

1. •NO HTML tags - Never use <br/>, <br>, or any HTML in any part of the diagram
2. •NO style directives - Never use style, fill, stroke, classDef, or color specifications
3. •Simple labels - Keep text concise, avoid special characters or escape them properly
4. •Validate syntax - Always check against common error patterns before finalizing

Quick Start

When generating any Mermaid diagram:

1. •Identify the diagram type (sequence, flowchart, class, state, ER)
2. •Use only the patterns from syntax-guide.md
3. •Avoid all forbidden patterns listed below
4. •Keep labels short and simple

Forbidden Patterns

These ALWAYS cause errors - never use:

❌ participant User<br/>Browser          (HTML tags)
❌ A[Label<br/>with breaks]              (HTML in labels)
❌ style A fill:#ff0000                  (Style directives)
❌ classDef myClass fill:#f9f            (Color definitions)
❌ A --> B: Very long message<br/>text   (Line breaks in text)

Safe Patterns

Use these instead:

✅ participant UserBrowser as User Browser    (Aliases)
✅ A[Short label]                             (Concise text)
✅ A --> B: Concise message                   (Single-line text)
✅ Note over A,B: Descriptive note            (Notes for details)

Diagram Type Selection

Choose based on use case:

• •Sequence diagrams: Authentication flows, API calls, time-based interactions
• •Flowcharts: Decision logic, processes, algorithms, step-by-step workflows
• •Class diagrams: Object-oriented design, data structures, type hierarchies
• •State diagrams: State machines, status lifecycles, transition logic
• •ER diagrams: Database schemas, entity relationships, data models

Generating Diagrams

Sequence Diagrams

Use for showing interactions over time (auth flows, API calls):

sequenceDiagram
    participant Client
    participant Auth0
    participant Backend

    Client->>Auth0: Login request
    Auth0-->>Client: Authorization code
    Client->>Backend: POST /create-session
    Backend-->>Client: Set-Cookie (session)

Key rules:

• •Use participant X as Long Name for readable labels
• •Arrow types: ->, -->, ->>, -->> (solid/dotted, with/without arrow)
• •Keep messages concise (no line breaks)
• •Use Note over X,Y: Text for additional context

See syntax-guide.md for complete sequence diagram syntax.

Flowcharts

Use for decision trees and processes:

flowchart TD
    A[Start]
    B{Authenticated?}
    C[Call API]
    D[Redirect to login]

    A --> B
    B -->|Yes| C
    B -->|No| D

Key rules:

• •Direction: TD (top-down), LR (left-right), BT (bottom-top), RL (right-left)
• •Shapes: [] rectangle, () rounded, {} diamond, [[]] subroutine
• •Use quotes for labels with special chars: A["Label: special"]

See syntax-guide.md for complete flowchart syntax.

Class Diagrams

Use for object-oriented design:

classDiagram
    class User {
        +String id
        +String email
        +login()
        +logout()
    }

    class Session {
        +String token
        +Date expires
        +validate()
    }

    User --> Session

Key rules:

• •Visibility: + public, - private, # protected
• •Relationships: <|-- inheritance, *-- composition, --> association
• •Keep type annotations simple

See syntax-guide.md for complete class diagram syntax.

State Diagrams

Use for state machines and lifecycles:

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing
    Processing --> Success
    Processing --> Failed
    Success --> [*]
    Failed --> [*]

Key rules:

• •Use stateDiagram-v2 (v2 is current version)
• •[*] represents start/end states
• •Avoid special characters in state names

See syntax-guide.md for complete state diagram syntax.

ER Diagrams

Use for database schemas:

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains

    USER {
        string id
        string email
    }

    ORDER {
        string id
        date created_at
    }

Key rules:

• •Cardinality: ||--|| one-to-one, ||--o{ one-to-many, }o--o{ many-to-many
• •Use hyphens in multi-word entity names: USER-ACCOUNT
• •Keep attribute types simple

See syntax-guide.md for complete ER diagram syntax.

Error Prevention Workflow

Before finalizing any Mermaid diagram:

1. •Check for HTML tags - Search for <br, <div, or any < character
2. •Check for style directives - Search for style, fill:, stroke:
3. •Check labels - Ensure all text is concise (no manual line breaks)
4. •Check special chars - Escape or quote labels with :, #, {}, [], ()
5. •Verify syntax - Match exactly against patterns in syntax-guide.md

Common Fixes

Resources

references/syntax-guide.md

Comprehensive syntax reference with:

• •Detailed syntax for all diagram types
• •Common pitfalls with examples
• •Validation checklist
• •Quick reference for diagram type selection

Load this file when encountering syntax questions or edge cases.