Mermaid 101: Diagrams as Text

What Is Mermaid?

Mermaid is a small, text-based language for describing diagrams. Instead of dragging shapes around a canvas, you write a few lines that look more like a to-do list than code, and a renderer turns them into a picture. The language was born in 2014 as a Markdown companion, and it is now understood out of the box by GitHub, GitLab, Notion, Obsidian, and almost every modern documentation pipeline.

Here is what Mermaid looks like — the source on the left, the rendered diagram on the right:

Left: nine lines of Mermaid. Right: the diagram the renderer produces. The text version lives in your repo; the picture is regenerated on demand.

This article is a pure 101 — what Mermaid is, why people use it, and the five diagram types that cover almost every real use. By the end you'll be able to read a Mermaid block at a glance and write one for any diagram you'd draw by hand. No tooling setup required; Mermaid is the rare technology that runs everywhere before you even ask.

Why Diagrams-as-Text?

The case for Mermaid is the same case as for Markdown over Word documents: text diffs cleanly. When a diagram is a PNG, the only way to know what changed between two versions is to squint at them side by side. When the diagram is Mermaid, git will tell you exactly which two lines moved. That single property unlocks a long list of workflow wins:

Review in a pull request. Someone adds a new state to a state machine? It shows up as a + line in the PR. Reviewers can comment on it the same way they comment on code.
Version history for free. git blame works on Mermaid. You can find out when a node was added, why it changed, who touched it last — same tooling as the code.
Search across the codebase. A diagram that's a PNG is invisible to grep. A Mermaid diagram is plain text, so grep "POST /login" finds it.
Authoring speed. Typing nine lines is usually faster than dragging nine shapes, especially once the syntax is in your fingers.
Automation. CI pipelines can validate that diagrams are in sync with code, auto-publish them to docs, or block PRs that reference non-existent nodes.

Mermaid isn't a replacement for every drawing — you can't hand-place a node, can't annotate with callouts, can't pick exactly the colours you want. But for the 80% of diagrams where "the default renderer's output is fine", it's far faster than any visual tool.

The Anatomy of a Mermaid Block

Every Mermaid diagram starts with a type declaration on the first line — one keyword that tells the renderer which grammar to use. Below that comes the body, which differs by type but always stays short and declarative.

The parts of any Mermaid block. A type keyword, a list of nodes, and a list of connections between them. That's essentially the whole language.

Five diagram types cover ~95% of real-world Mermaid usage. We'll walk through each one below.

1. Flowchart

The workhorse. Boxes, arrows, decisions — anything shaped like a flow. The keyword is flowchart followed by a direction: TD (top-down), LR (left-right), BT (bottom-top), or RL (right-left).

Node shapes are indicated by the brackets around the label:

A[Rectangle] — plain rectangle, the default.
A(Rounded) — rounded rectangle; use for processes.
A((Circle)) — circle; use for start/end or small labels.
A{Diamond} — decision diamond.
A[[Subroutine]] — subroutine box (rectangle with double sides).
A[(Database)] — cylinder; use for data stores.

Connections between nodes use arrow variants:

A --> B — solid arrow.
A --- B — line with no arrowhead.
A -.-> B — dashed arrow.
A ==> B — thick arrow.
A -->|label| B — arrow with a label.

A flowchart showing all the common shapes. Circles for terminators, rectangle for actions, diamond for decisions, cylinder for a database, double-sided box for a subroutine.

2. Sequence Diagram

Used for any flow over time: API calls, function calls, conversations between services. The keyword is sequenceDiagram. Participants go at the top; messages flow down.

The arrow syntax encodes the message type:

A->>B: msg — solid arrow: synchronous (the caller waits).
A-->>B: reply — dashed arrow: a return.
A-)B: msg — open-arrow async: fire-and-forget.
A->>A: self — same participant on both sides: self-message.

You can wrap messages in alt, opt, loop, or par blocks to express branching, optional, looping, and parallel behaviour.

A login sequence in Mermaid. Solid arrows are requests, dashed arrows are replies — the syntax is designed to match the visual convention.

3. Class Diagram

For object-oriented designs: classes, attributes, methods, relationships. The keyword is classDiagram. Each class gets its own block with fields and methods; relationships between classes are separate lines.

Relationship syntax matches the UML convention:

A <|-- B — inheritance (B extends A).
A *-- B — composition (A owns B).
A o-- B — aggregation (A has B).
A --> B — association.
A ..> B — dependency (dashed).
A ..|> B — realization (implements interface).

A minimal class diagram. Two classes, one inheritance relationship (the <|--). Mermaid renders three-compartment UML boxes automatically.

4. Entity-Relationship Diagram

For database schemas and data models. The keyword is erDiagram. Entities are named in uppercase, attributes live in { } blocks, and relationships use crow's foot notation in text form.

Relationship cardinality is encoded in the arrow characters:

|| — exactly one.
o| — zero or one.
|{ — one or many.
o{ — zero or many.

Reading left-to-right: USER ||--o{ POST means "one user has zero or many posts".

An ER diagram. ||--o{ is read as "exactly one on the left, zero or many on the right". Crow's foot notation, encoded in ASCII.

5. State Diagram

For lifecycle modelling: state machines, workflows, anything where "what state is this in?" changes over time. The keyword is stateDiagram-v2. States are named; transitions connect them with arrows.

Key syntax:

[*] --> Draft — the initial state (first line of any state machine).
Draft --> Submitted : submit — transition triggered by an event.
Archived --> [*] — the final state.

A state diagram of a blog post's lifecycle. Five lines of Mermaid, one complete picture of the allowed states and transitions.

Where Mermaid Fits in Your Workflow

The single biggest win from Mermaid is that the diagram lives next to the code. A few concrete patterns worth adopting:

In Markdown docs. Both GitHub and GitLab render Mermaid fenced code blocks in .md files automatically. Paste a diagram into any README, any design doc, any issue — it just works.
In pull requests. Updating a class structure? Update the class diagram in the same PR. Reviewers can comment on the diagram changes the same way they comment on code changes.
In architecture decision records (ADRs). When writing "we chose this design because…", a sequence diagram makes the trade-offs concrete in a way prose can't.
In runbooks. A flowchart showing the incident-response decision tree, committed to the ops repo, updated every time the playbook changes.
In generated docs. Tools like MkDocs, Docusaurus, and VitePress render Mermaid blocks in their output. Your diagrams become part of the published documentation without any extra pipeline work.

When Mermaid isn't the right tool: anything where you need hand-placement of nodes, custom colours beyond themes, or annotation callouts. The moment you want "this arrow should bend around that box and have a sticky note attached", you've outgrown what the renderer does and you should move to a visual drawing tool.

Common Gotchas

A handful of small things trip up nearly every beginner.

Special characters in labels. Brackets, quotes, colons, and ampersands in node labels confuse the parser. Wrap the label in double quotes: A["Label with (parens)"].
Reserved words as IDs. end, class, state, and a few others are reserved. Don't name a node end — use End (capital E) or pick another name.
Indentation is cosmetic, not syntactic. Mermaid doesn't care about leading whitespace, but humans do. Keep it consistent.
Type declaration on line 1. The first non-blank line has to be the diagram-type keyword. Comments or blank lines before it are fine; anything else isn't.
Renderer differences. Mermaid's official playground, GitHub's render, Notion's render, and VS Code plugins sometimes lag a version behind each other. If a diagram works in one place and breaks in another, check which Mermaid version each supports.
Readable diagrams are short diagrams. A Mermaid flowchart with 40 nodes is just as unreadable as a visual flowchart with 40 nodes. Break it up — one diagram per question, same as always.

Where to Go Next

Mermaid supports a handful of diagram types beyond the five covered here — Gantt charts, pie charts, user journey maps, Git graphs, mindmaps, timelines, and C4 architecture diagrams. Most of them are niche enough to learn when you need them; the five here do nearly all the real work.

Two follow-on skills compound well with Mermaid:

Learn the visual conventions of each diagram type. The companion 101 articles on this blog cover ER diagrams, UML class diagrams, sequence diagrams, flowcharts, and mind maps in depth. Mermaid is the syntax; those articles teach the notation.
Set up live previews in your editor. VS Code's "Markdown Preview Mermaid Support" extension gives you a real-time rendered preview as you type. The tightening of the feedback loop matters more than you'd expect.

A Note on Tools

Mermaid itself is open source and runs inside most documentation platforms out of the box — you rarely need to install anything. The live playground at mermaid.live is the fastest way to experiment with syntax. If you'd like to take a Mermaid block and turn it into an editable, hand-drawn visual for a presentation or a polished design doc, CorriDraw — the tool you're reading this on — ships with a Mermaid import that converts the text into movable, restyleable shapes on a canvas. But the language itself is the thing worth knowing, and it works the same everywhere.