Mermaid Syntax: A Working Cheat Sheet for Sequence, ER, and Class Diagrams

Mermaid turns plain text into real diagrams. One keyword declares the diagram type, then each line is a statement the renderer draws for you — no dragging boxes, no aligning arrows. That makes it the fastest way to get a sequence, ER, or class diagram into a README or a design doc, and the easiest one to update in a pull request. Here's the syntax that covers 95% of real-world diagrams, plus the handful of mistakes that break almost every first render.

What is Mermaid syntax?

Every Mermaid block starts with a diagram type keyword on the first line. Everything after it is the diagram body, one statement per line:

flowchart TD
    A[Start] --> B{Is it written in text?}
    B -- Yes --> C[Use Mermaid]
    B -- No --> D[Draw it by hand]

That's the whole mental model. The keyword says what kind of picture; the lines say what's in it. Mermaid (MIT-licensed, free for anything including commercial use) renders it client-side, which is why GitHub, GitLab, and Notion display Mermaid blocks in markdown files without any plugin. The same block pasted into the Mermaid diagram suite renders live and exports SVG or PNG.

The most useful type keywords: flowchart (boxes and arrows), sequenceDiagram (interactions over time), erDiagram (database entities), classDiagram (code structure), and gantt (timelines). Flowcharts and Gantt charts have their own dedicated builders here — the flowchart maker and Gantt chart maker — so this guide focuses on the three text-first diagram types where Mermaid is the de facto standard.

How do you write a sequence diagram in Mermaid?

Sequence diagrams show messages between actors over time. The skeleton:

sequenceDiagram
    actor U as User
    participant A as App
    participant S as Auth Server

    U->>A: Tap "Sign in"
    A->>S: POST /login
    activate S
    S-->>A: 200 OK + token
    deactivate S
    A-->>U: Show dashboard

    loop Every page load
        A->>S: Validate token
        S-->>A: valid
    end

Read the arrows like this:

actor draws a stick figure, participant a box; both take an as alias so your code says S and readers see "Auth Server". The sequence diagram maker runs this live with a cheatsheet alongside the editor.

How do you draw an ER diagram in Mermaid?

ER diagrams in Mermaid are relationship-first. Each line connects two entities with crow's-foot notation on the line itself:

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

    CUSTOMER {
        string email PK
        string name
    }
    ORDER {
        int id PK
        string customer_email FK
        date placed_on
    }

The cardinality marks are the part worth memorizing — each side of the dashed line gets one:

So CUSTOMER ||--o{ ORDER reads left to right: one customer, zero-or-many orders. Attribute blocks go under an entity by name, one attribute per line as type name key, where key is PK, FK, or UK for unique. Try your schema in the ER diagram maker — it keeps the crow's-foot table on screen while you type.

How do you draw a class diagram in Mermaid?

Class diagrams describe code structure: classes, their members, and how they relate. Members use visibility symbols borrowed from UML:

classDiagram
    class Account {
        +String owner
        -int balance_cents
        +deposit(int amount) bool
        -validate() void
    }
    Account <|-- SavingsAccount
    Account <|-- CheckingAccount
    Bank "1" *-- "many" Account : holds
    Statement o-- Account : summarizes

The class diagram maker has the full member and relationship table next to a live editor.

Why won't my Mermaid diagram render?

Almost every broken diagram comes down to one of five things:

1. Missing or misspelled first line. The diagram type must be the very first token: sequenceDiagram is one word, erDiagram is camelCase, flowchart TD needs a direction.
2. Special characters in labels. Parentheses, quotes, and colons inside node text need the label wrapped in quotes: A["Login (retry)"] instead of A[Login (retry)].
3. Wrong arrow for the diagram type. Flowcharts use -->; sequence diagrams need ->> for messages. ER diagrams don't use arrows at all — cardinality marks joined by a dashed line.
4. Stray text on end lines. Frames close with end alone. end # comment breaks the parser in several versions.
5. Indentation surprises. Mermaid is mostly indent-insensitive, but tabs mixed with spaces inside class member blocks can fail. Stick to consistent spaces.

The fastest fix loop: paste the block into the live suite editor, and the error view points at the failing line. Then re-export or copy the corrected text back into your doc.

FAQ

Related tools: