Mermaid.js lets you generate diagrams from text. Instead of dragging boxes in a visual editor, you write a few lines of syntax and get a rendered diagram. This makes diagrams version-controllable, easy to embed in markdown, and fast to update. Here's a practical reference for the most useful diagram types.

Flowcharts

The most common Mermaid diagram. Define nodes and connections:

flowchart TD
    A[Start] --> B{Is it valid?}
    B -- Yes --> C[Process request]
    B -- No --> D[Show error]
    C --> E[Return response]
    D --> E

Node shapes are determined by the brackets:

Advertisement

Directions: TD (top-down), LR (left-right), BT (bottom-up), RL (right-left).

Sequence Diagrams

sequenceDiagram
    participant C as Client
    participant S as Server
    participant D as Database
    C->>S: GET /api/users
    S->>D: SELECT * FROM users
    D-->>S: Return rows
    S-->>C: 200 OK + JSON
    Note over C,S: Response cached for 5 min

Arrow types: ->> (solid), -->> (dashed), -x (solid with X), --x (dashed with X). Use autonumber at the top to add sequence numbers automatically.

ER Diagrams

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    CUSTOMER {
        int id PK
        string name
        string email
    }
    ORDER {
        int id PK
        int customer_id FK
        date order_date
    }

Relationship cardinality: ||--|| (one-to-one), ||--o{ (one-to-many, optional), }o--o{ (many-to-many).

State Diagrams

stateDiagram-v2
    [*] --> Idle
    Idle --> Loading : user clicks
    Loading --> Success : data received
    Loading --> Error : timeout
    Error --> Idle : retry
    Success --> [*]

Class Diagrams

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound() void
    }
    class Dog {
        +String breed
        +fetch() void
    }
    Animal <|-- Dog

Visibility: + public, - private, # protected. Relationships: <|-- inheritance, *-- composition, o-- aggregation.

Gantt Charts

gantt
    title Project Timeline
    dateFormat YYYY-MM-DD
    section Design
    Research :done, a1, 2026-01-01, 7d
    Wireframes :a2, after a1, 5d
    section Development
    Backend :a3, after a2, 14d
    Frontend :a4, after a2, 10d

Tips for Readable Diagrams

The diagram tool on this site renders Mermaid syntax in real time. Paste your code, and see the diagram instantly. Everything runs in your browser — no server, no data upload. Export as SVG when you're ready to use the diagram in documentation.