Mermaid Diagram Syntax Reference

Tentarc renders Mermaid diagrams natively as beautiful themed SVGs. Use this reference for syntax details.

Flowcharts

Header: graph LR (left-right, preferred) or graph TD (top-down) Directions: LR (preferred), RL, TD, TB, BT

Node Shapes

Arrow Types

Edge Labels

graph LR
    A -->|label text| B
    C -- label text --> D

Subgraphs

graph LR
    subgraph Backend
        API --> DB
    end
    subgraph Frontend
        UI --> API
    end
    Client --> UI

Subgraph with ID

graph TD
    subgraph backend-services [Backend Services]
        direction LR
        API --> Cache
        API --> DB
    end

Styling

graph LR
    A[Start]:::highlight --> B[End]
    classDef highlight fill:#f9f,stroke:#333
    style B fill:#bbf,stroke:#333

Chained Edges

graph LR
    A --> B --> C --> D

Parallel Links

graph LR
    A & B --> C & D

State Diagrams

Header: stateDiagram-v2

Basic States

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing: start
    Processing --> Complete: done
    Processing --> Error: fail
    Complete --> [*]
    Error --> Idle: retry

State Descriptions

stateDiagram-v2
    state "Waiting for input" as Waiting
    Waiting --> Processing

Composite States

stateDiagram-v2
    state "Active" as Active {
        Running --> Paused: pause
        Paused --> Running: resume
    }
    [*] --> Active
    Active --> [*]: complete

Direction Override

stateDiagram-v2
    direction LR
    [*] --> A --> B --> [*]

Sequence Diagrams

Header: sequenceDiagram

Message Types

Participants

sequenceDiagram
    participant C as Client
    participant S as Server
    participant DB as Database

    C->>S: POST /api/users
    S->>DB: INSERT user
    DB-->>S: OK
    S-->>C: 201 Created

Activations

sequenceDiagram
    Client->>+Server: Request
    Server->>+Database: Query
    Database-->>-Server: Results
    Server-->>-Client: Response

Notes

sequenceDiagram
    Alice->>Bob: Hello
    Note right of Bob: Bob thinks
    Bob-->>Alice: Hi!
    Note over Alice,Bob: Conversation complete

Loops

sequenceDiagram
    loop Every minute
        Client->>Server: Heartbeat
        Server-->>Client: ACK
    end

Alternatives

sequenceDiagram
    Client->>Server: Request
    alt Success
        Server-->>Client: 200 OK
    else Failure
        Server-->>Client: 500 Error
    end

Optional

sequenceDiagram
    opt If cached
        Server-->>Client: Cached response
    end

Parallel

sequenceDiagram
    par Parallel requests
        Client->>ServiceA: Request A
    and
        Client->>ServiceB: Request B
    end

Class Diagrams

Header: classDiagram

Classes with Members

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound() void
        +move(distance) void
    }

Visibility Modifiers

Relationships

Cardinality

classDiagram
    Customer "1" --> "*" Order : places
    Order "1" *-- "1..*" LineItem : contains

Full Example

classDiagram
    class Animal {
        <<abstract>>
        +String name
        +int age
        +makeSound()* void
    }

    class Dog {
        +String breed
        +bark() void
    }

    class Cat {
        +bool indoor
        +meow() void
    }

    Animal <|-- Dog
    Animal <|-- Cat

Annotations

classDiagram
    class Service {
        <<interface>>
        +start() void
        +stop() void
    }

    class Logger {
        <<singleton>>
        -instance Logger
        +log(msg) void
    }

ER Diagrams

Header: erDiagram

Basic Relationships

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : "is in"

Cardinality Notation

Entity Attributes

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

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

    USER ||--o{ ORDER : places

Attribute Types

Common attribute markers:

• PK - Primary Key
• FK - Foreign Key
• UK - Unique Key

Full Example

erDiagram
    CUSTOMER {
        int id PK
        string email UK
        string name
        string phone
    }

    ORDER {
        int id PK
        int customer_id FK
        date order_date
        string status
    }

    PRODUCT {
        int id PK
        string name
        decimal price
        int stock
    }

    LINE_ITEM {
        int id PK
        int order_id FK
        int product_id FK
        int quantity
        decimal unit_price
    }

    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : "included in"

Best Practices

Prefer Horizontal (Landscape) Orientations

IMPORTANT: Use horizontal layouts (LR, RL) whenever possible. Horizontal diagrams are much easier to view and navigate in the UI.

• Flowcharts: Use graph LR (left-right) instead of graph TD (top-down)
• State Diagrams: Add direction LR after the header
• Sequence Diagrams: Naturally horizontal, no changes needed
• Class Diagrams: For wide hierarchies, consider splitting into multiple horizontal diagrams
• ER Diagrams: Naturally horizontal, no changes needed

Only use vertical layouts (TD, BT) when:

• The diagram is inherently hierarchical (org charts, tree structures)
• The vertical layout is significantly clearer than horizontal
• The diagram has very few nodes (3-4 max)

Keep Diagrams Focused

One concept per diagram. If a diagram gets complex, split it into multiple diagrams.

Use Descriptive Labels

graph LR
    A[User submits form] --> B{Validation}
    B -->|Valid| C[Save to database]
    B -->|Invalid| D[Show errors]

Choose the Right Direction

Horizontal (preferred):

• LR (left-right): DEFAULT - Use for flows, pipelines, state machines, processes, and most diagrams
• RL (right-left): Reverse flows (when semantically meaningful)

Vertical (use sparingly):

• TD (top-down): Only for hierarchies, inheritance, org charts where vertical structure is essential
• BT (bottom-top): Only for dependencies pointing upward

Validate Complex Diagrams

Use the mermaid_validate tool to check syntax before outputting complex diagrams:

mermaid_validate({ code: "graph TD\n  A --> B" })

Troubleshooting

Common Errors

1. Missing direction: Always include direction in flowcharts (graph TD, not just graph)
2. Unbalanced brackets: Ensure all [, (, { are properly closed
3. Special characters in labels: Use quotes for labels with special characters
4. Invalid arrow syntax: Check the arrow type table above

Escaping Special Characters

For labels with special characters, wrap in quotes:

graph LR
    A["Label with (parentheses)"] --> B["Label with [brackets]"]