Create Diagrams with Mermaid — Flowcharts, Sequences & More

Mermaid is a text-based diagramming language: you describe a diagram in a few lines of plain text and it is drawn automatically. There is no dragging boxes, no aligning arrows and no binary files — your diagrams live next to your code and documentation, can be reviewed in pull requests and are easy to update. This tutorial walks through the most useful diagram types with examples you can copy.

Why use Mermaid?

• Diagrams as code. Diagrams are stored as text, so you get version control, diffs and code review for free.
• Fast to edit. Renaming a step or adding a branch takes seconds — the layout is recalculated automatically.
• Renders in many tools. GitHub, GitLab, Notion, Obsidian, Azure DevOps, Docusaurus and MkDocs (with a plugin or theme) display Mermaid code blocks as diagrams.

To embed a diagram in Markdown, put the code in a fenced block with the mermaid language:

```mermaid
flowchart LR
    A --> B
```

Flowcharts

Flowcharts are the most common Mermaid diagram. Start with flowchart and a direction: TD (top-down), LR (left-right), BT or RL.

flowchart TD
    A[Start] --> B{Logged in?}
    B -->|Yes| C[Show dashboard]
    B -->|No| D[Show login form]
    D --> E((Submit))
    E --> B

Node shapes

Links

Group related nodes with subgraph:

flowchart LR
    subgraph Frontend
        UI[Web app]
    end
    subgraph Backend
        API[REST API] --> DB[(PostgreSQL)]
    end
    UI --> API

Sequence diagrams

Sequence diagrams show how components talk to each other over time — perfect for documenting APIs and authentication flows.

sequenceDiagram
    participant U as User
    participant A as App
    participant S as Auth Server
    U->>A: Click "Sign in"
    A->>S: Authorization request
    S-->>U: Login page
    U->>S: Credentials
    S-->>A: Authorization code
    A->>S: Exchange code for token
    S-->>A: Access token
    Note over A,S: Token is valid for 1 hour

->> is a solid arrow (request), -->> is a dashed arrow (response). Use Note over, loop, alt/else and opt blocks for comments and conditional logic.

Class diagrams

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

<|-- means inheritance; *-- is composition, o-- aggregation and --> association.

State diagrams

stateDiagram-v2
    [*] --> Draft
    Draft --> Review: submit
    Review --> Draft: request changes
    Review --> Published: approve
    Published --> [*]

[*] marks the start and end states.

Entity-relationship (ER) diagrams

ER diagrams document database schemas:

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ ORDER_ITEM : contains
    PRODUCT ||--o{ ORDER_ITEM : "is in"

The symbols describe cardinality: || exactly one, o{ zero or more, |{ one or more.

Gantt charts

gantt
    title Website launch
    dateFormat YYYY-MM-DD
    section Design
    Wireframes      :a1, 2026-11-02, 5d
    Visual design   :a2, after a1, 7d
    section Development
    Frontend        :b1, after a2, 10d
    Backend         :b2, after a2, 12d
    section Launch
    QA and release  :after b2, 4d

Pie charts

pie title Traffic sources
    "Search" : 52
    "Direct" : 23
    "Social" : 15
    "Referral" : 10

Mind maps

Mind maps use indentation to define the hierarchy:

mindmap
  root((Product launch))
    Marketing
      Blog post
      Newsletter
    Engineering
      Release notes
      Monitoring
    Support
      FAQ

Tips and common errors

• Quote labels with special characters: A["Price (USD)"]. Parentheses, brackets and quotes inside unquoted labels break parsing.
• Add comments with %%, for example %% TODO: add error path.
• Avoid reserved words like end as a node ID — use End or finish instead.
• Keep diagrams small. If a flowchart has more than ~15 nodes, split it into several diagrams.
• Check the version. Platforms update Mermaid at different times; newer diagram types may not render everywhere yet.

How to export a Mermaid diagram

Open the free Mermaid editor, pick a template or paste your code, then:

• PNG — for slides, chats and documents.
• SVG — for websites and print (sharp at any size).
• Copy as Markdown — paste the code block into GitHub, Notion or Obsidian.

Styling and themes

Mermaid has built-in themes: default, neutral, dark and forest. Set one for a single diagram with an init directive on the first line:

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    A[Draft] --> B[Review] --> C[Publish]

To highlight specific nodes, define a class and apply it:

flowchart LR
    A[Order placed] --> B[Payment] --> C[Shipped]
    classDef done fill:#d1fae5,stroke:#10b981;
    classDef current fill:#fef3c7,stroke:#f59e0b;
    class A done
    class B current

Keep styling minimal in documentation: platforms like GitHub switch between light and dark mode, and hard-coded colors may become hard to read in one of them.

More diagram types

Mermaid supports more than the examples above. A few worth knowing:

• User journey (journey) — maps the steps of a user experience with satisfaction scores.
• Timeline (timeline) — events grouped by period, good for project history.
• Git graph (gitGraph) — visualizes branches, commits and merges, useful for explaining a branching strategy.
• Quadrant chart (quadrantChart) — the classic 2×2 prioritization matrix.

Support for newer types depends on the Mermaid version used by each platform, so preview your diagram where it will be published.

A workflow that scales

1. Sketch the diagram in the Mermaid editor with live preview.
2. Commit the Mermaid code in your Markdown docs, so it is reviewed together with the code it describes.
3. Export PNG or SVG only for places that cannot render Mermaid, such as slides or PDF reports.

Frequently asked questions

Does GitHub support Mermaid?

Yes. Mermaid code blocks are rendered as diagrams in READMEs, issues, pull requests, discussions and wikis.

Is Mermaid free?

Yes. Mermaid is an open-source JavaScript library, and the MarkdownNote Mermaid editor is free to use.

Can I use Mermaid in presentations?

Export the diagram as PNG or SVG and add it to your slides, or include it as an image in a Markdown presentation.