Authoring Mermaid diagrams that actually render

Mermaid's parser is strict, line-oriented, and not standardized across renderers — GitHub, Mermaid Live, and the mermaid-js versions embedded in various IDEs all differ. The rules below are the conservative subset that renders everywhere. Follow them by default; only deviate when you've verified the target renderer supports a feature.

Verifying the target renderer

When a feature outside the conservative subset is tempting, probe the engine first: render a fenced mermaid block containing only

info

It prints the engine's mermaid version (works on GitHub and Mermaid Live). Interactive features (click links / callbacks) never run in static or sandboxed renderers such as GitHub, regardless of version.

Where the diagram lives

Two wrappers, identical syntax inside:

• Inside markdown (READMEs, ADRs — the common case): a triple-backtick fence tagged mermaid.
• Standalone .mmd / .mermaid file: no fence — the file starts directly with the diagram type. Use when the diagram deserves its own file or you'll render it to SVG/PNG via the mmdc CLI and embed it as an image.

Every rule below applies to both.

Hard rules — apply unconditionally

R1. Use only ASCII arrows. Never put unicode arrows in messages or labels.

Some renderers tokenize →, ⇄, ↔, ⇒, ← as arrow operators even inside message text or node labels, which corrupts parsing of the surrounding line.

R2. In sequenceDiagram, use only these arrow forms.

Avoid by default --), -), -(, --(. These "async open-arrow" forms are rejected only by renderers embedding mermaid <= 8.x (2020-era), with errors like Expecting 'SOLID_OPEN_ARROW'...; all mainstream 2026 renderers (GitHub, Mermaid Live, current IDEs) accept them. When targeting unknown or legacy embedded renderers, replace every --) with -->> (same semantics: dashed async reply).

R3. Never put ; in message text or Note text.

In sequence diagrams, semicolon ends the statement. Everything after it is parsed as a new statement and explodes with Expecting <signal type> or ID, got ';' or Expecting NEWLINE.

Use commas or - instead. If a literal semicolon is required in the text, use the entity escape #59;.

R4. Default to - separators in participant ... as aliases; use <br/> only on verified renderers.

Current mermaid (11.x) supports <br/> line breaks in participant aliases — the official docs document participant Alice as Alice<br/>Johnson as the line-break mechanism for actor names, and it renders as a real two-line label. But some older embedded renderers abort alias parsing on it, and the next token (often a comma in a later Note over A,B) becomes "unexpected."

Default to - or / as a separator, or split into two participants; use <br/> only after confirming the target renderer (see the info probe above). <br/> in flowchart / graph node labels (A[Line 1<br/>Line 2]) is safe everywhere.

R5. Avoid reserved / ambiguous identifiers for participants and nodes.

Mermaid reserves keywords used by its own syntax. The biggest landmine in sequence diagrams: off (used by autonumber off). Sequence-diagram lexing is case-insensitive, so OFF, End, and Box all collide there. Flowcharts are the opposite — ids are case-SENSITIVE: End renders fine while lowercase end is a parse error, and capitalizing end is mermaid's own documented workaround for the flowchart end-keyword collision.

Other words to avoid as IDs: end, class, click, link, note, loop, alt, else, opt, par, and, rect, activate, deactivate, participant, actor, as, over, on, off, default, direction, subgraph, box, critical, break, create, destroy, links, properties, details.

Flowchart edge-decoration gotcha: a node id starting with lowercase o or x directly after an edge is parsed as a circle/cross edge decoration — A---oB silently becomes an o-decorated edge to B. Capitalize or add a space: A---OB or A--- oB.

R6. Style subgraphs with a class statement or style — never the inline ::: shorthand.

class subgraphId styleName works in current mermaid (the class lands on the subgraph's cluster element), and style subgraphId fill:#... works everywhere. The inline shorthand on a subgraph declaration — subgraph id:::styleName — is a parse error. Old embedded renderers (mermaid <= 8.7, bug mermaid-js#1726, fixed Oct 2020) rendered fine but silently dropped the class on subgraphs, so style subgraphId ... remains the safest cross-renderer choice.

R7. Quote node labels that contain special characters.

In flowchart / graph, wrap labels in double quotes whenever the label contains (, ), {, }, :, ,, /, &, |, <, >, #, or pipe characters.

GOOD:  API["Chat SSE: POST /api/v1/chat/{conv_id}"]
BAD:   API[Chat SSE: POST /api/v1/chat/{conv_id}]

R8. Edge labels with special characters must be quoted.

GOOD:  A -->|"HTTP chat SSE"| B
BAD:   A -->|HTTP chat (SSE)| B

R9. Don't mix link styles into one chain you also try to label individually.

A --> B --> C is fine, but if any link needs a label, write the labeled link on its own line:

A --> B
B -->|"with label"| C

Soft rules — apply by default, relax only when needed

S1. Prefer ASCII punctuation in message text.

Em dashes (—) and curly quotes usually render, but some embedded renderers strip or misinterpret them. When in doubt, use - and straight quotes.

S2. Keep one statement per line. No trailing semicolons.

Even where Mermaid allows ; as a separator, omitting it removes a whole class of bugs.

S3. Keep participant / node ids short and ALL_CAPS or PascalCase.

Short ids are less likely to collide with reserved words and keep diffs readable. Put the long human-readable name in the as alias.

S4. For sequence diagrams, declare every participant explicitly with participant.

Auto-declaration (first appearance) sometimes orders participants unexpectedly and makes reserved-word collisions harder to diagnose.

Pre-flight checklist (run mentally before emitting any Mermaid block)

1. Arrows: search the block for →, ⇄, ↔, ⇒, ←. Replace with ASCII (to, to/from, etc.).
2. Sequence arrows: search for --), -), -(, --(. Replace --) with -->>.
3. Semicolons: search for ; in Note lines and in message text (after a :). Replace with , or -.
4. <br/> in sequence participants: search for participant .* as .*<br/>. Replace with - unless the target renderer is verified mermaid 11.x (R4).
5. Reserved ids: search for participant / node ids matching (case-insensitive in sequence diagrams; flowchart ids are case-sensitive) off|end|class|note|loop|link|on|as|over|alt|else|opt|par|and|rect|activate|deactivate|default|direction|subgraph|box|critical|break|create|destroy|links|properties|details. Rename. Also in flowcharts: search for edges directly followed by an id starting with lowercase o/x (e.g. ---oB); capitalize or add a space.
6. Subgraph styling: in flowchart / graph, no inline ::: on a subgraph declaration — use class subgraphId name on its own line, or style subgraphId fill:#... (safest cross-renderer).
7. Unquoted special chars in labels: search for [ ... ( ... ] patterns and [ ... : ... ]. Quote those labels: X["..."].
8. Edge labels with special chars: quote -->|"..."|.

If any check fails, fix before emitting the block.

Error message → fix table (for debugging an existing diagram)

Canonical safe templates

Drop one of these in and edit; they all pass the pre-flight checklist by construction.

Sequence diagram

sequenceDiagram
    autonumber
    participant UI as Browser UI
    participant SRV as Server
    participant DB as Database

    UI->>SRV: POST /login (credentials)
    SRV->>DB: SELECT user
    DB-->>SRV: row
    SRV-->>UI: 200 OK, JWT
    Note over UI,SRV: session established, JWT in cookie

Flowchart with subgraphs + styling

flowchart TB
    subgraph client["Client"]
        UI["Browser UI"]
    end

    subgraph server["Server (Rust)"]
        API["POST /api/v1/x"]
        SVC["Service layer"]
    end

    UI -->|"HTTPS"| API
    API --> SVC

    classDef rust fill:#f8d7a0,stroke:#c47f17
    class API,SVC rust
    style server fill:#fff7e6,stroke:#c47f17

State diagram

stateDiagram-v2
    [*] --> Idle
    Idle --> Active: start
    Active --> Idle: end_turn
    Active --> Cancelling: barge_in
    Cancelling --> Idle: drained
    Active --> PermissionPending: tool needs auth
    PermissionPending --> Active: decided

Class diagram

classDiagram
    class Order {
        +UUID id
        +Money total
        +place()
        +cancel()
    }
    class Item {
        +UUID sku
        +int quantity
    }
    Order "1" *-- "many" Item

A note on other diagram types

Mermaid also supports erDiagram, gantt, gitGraph, journey, pie, mindmap, timeline, quadrantChart, sankey, xychart, architecture-beta, block, kanban, packet, radar, and treemap. The rules above (no unicode arrows, no ; in text, quote special-char labels, avoid reserved ids) apply uniformly. For type-specific syntax see the Mermaid docs.