explainer

Mermaid diagrams in documentation, with examples

A diagram written as text lives in the same file as the words, reviews like a paragraph and never goes stale in a folder of PNGs. Five diagram types worth using, what each one is for, and when prose is the better answer.

published 10 September 2026 · 6 min read

the short version

Write diagrams as text in the same file as the prose. They review like a paragraph, they never drift from the docs they illustrate, and nobody has to find the original file to change an arrow.

Start for free See Docszero pricing

Why a diagram should be text

The diagram problem in documentation is never drawing it. It is the second year. Someone drew a good architecture picture, exported a PNG, dropped it in the repo, and left the company. The system changed twice. Nobody can open the source, so the picture stays wrong, and eventually a reader trusts it.

Mermaid fixes that by making the diagram part of the document. You write a fenced code block, it renders as a picture, and the picture is generated from text that sits four lines below the paragraph it illustrates.

A wrong arrow is a one-word diff, reviewable like any other change.
There is no source file to lose, and no licence to a drawing tool to maintain.
The diagram travels with the Markdown, including through an export.
Someone who cannot open a design tool can still fix the docs.

In Docszero a fenced mermaid block renders in the browser preview and on the published page, on every plan including Free. There is no plugin to install and no build setting to switch on.

A flowchart, for a decision or a path

The one people reach for first, and the one most often misused. A flowchart earns its place when there are branches. If your process is six steps in a row with no decisions, a numbered list is clearer and takes a tenth of the space.

a publish path, with the two decisions that matter

```mermaid
flowchart TD
    A[Push to main] --> B{Docs changed?}
    B -- No --> C[Skip build]
    B -- Yes --> D[Build site]
    D --> E{Build passed?}
    E -- No --> F[Keep last live build]
    E -- Yes --> G[Publish]
```

TD sets the direction, top-down; LR runs it left to right, which usually suits a wide screen better. Square brackets make a box, curly braces make a decision diamond, and the text after -- labels the arrow.

A sequence diagram, for who calls whom

The most useful diagram in API documentation, and the most underused. Prose is genuinely bad at describing four parties exchanging messages in order; a sequence diagram is exactly that and nothing else.

a request that hits the cache, and one that cannot

```mermaid
sequenceDiagram
    autonumber
    participant R as Reader
    participant CDN
    participant App
    participant DB

    R->>CDN: GET /guide/install
    CDN-->>R: 200 (cached)
    R->>App: GET /private/runbook
    App->>DB: check site password
    DB-->>App: hash
    App-->>R: 302 to login
```

->> is a solid arrow for a call, -->> a dashed one for a response — worth keeping consistent, because a reader learns the convention in the first diagram and applies it to every later one. autonumber adds step numbers, which makes the diagram citable from the prose: "at step 4…".

A state diagram, for a thing with a lifecycle

Anything in your product with a status field probably deserves one of these. A state diagram answers the questions a table of statuses cannot: which transitions are legal, and which are dead ends.

a build, and the fact that a failure never replaces what is live

```mermaid
stateDiagram-v2
    [*] --> Queued
    Queued --> Building
    Building --> Live: success
    Building --> Failed: error
    Failed --> Queued: retry
    Live --> Building: republish
    Live --> [*]
```

[*] is the start and end. The text after the colon labels the transition. The thing this diagram says that a paragraph would bury: there is no arrow from Failed to Live, so a failed build cannot become the published site.

Two more worth knowing

An entity relationship diagram, for a data model

Cheaper than a table of foreign keys and much easier to scan. The crow’s-foot notation carries the cardinality, so you do not have to write "one to many" in prose beside it.

one account, many projects, and a domain that is optional

```mermaid
erDiagram
    ACCOUNT ||--o{ PROJECT : owns
    PROJECT ||--o{ BUILD : produces
    BUILD ||--|| ARTIFACT : stores
    PROJECT }o--o| DOMAIN : "answers at"
```

A gantt chart, for a migration with dates

Not for project management — nobody wants to maintain a plan in Markdown. It is genuinely good for a deprecation timeline, where the dates are few, fixed, and the whole point.

a deprecation timeline, which is the honest use for a gantt

```mermaid
gantt
    title API v1 deprecation
    dateFormat YYYY-MM-DD
    section Notice
    Deprecation announced   :done, 2026-01-15, 30d
    section Migration
    v2 available            :active, 2026-02-15, 120d
    section Shutdown
    v1 read-only            :2026-06-15, 30d
    v1 removed              :milestone, 2026-07-15, 0d
```

When not to draw one

A diagram is a claim that the shape of a thing matters more than its details. Often it does not, and the diagram becomes decoration that still has to be maintained.

If the content is	Use
Steps in order, no branches	A numbered list
A decision with two or three branches	A flowchart
Parties exchanging messages in order	A sequence diagram
A status field and its legal transitions	A state diagram
Tables and how they relate	An ER diagram
Comparable values across options	A table, not a chart
A screenshot of your own interface	A screenshot
A system with forty boxes	Three diagrams, one per layer

The forty-box case is the common failure. A diagram nobody can read at the width of a docs page has not communicated anything; it has just moved the confusion into a picture. Split it by layer, or by the path one request takes, and let each diagram answer one question.

Questions

How do I add a Mermaid diagram to Markdown?

Open a fenced code block, mark it as mermaid, write the diagram body and close the fence. In Docszero it renders in the browser preview and on the published page on every plan, including Free, with no plugin to install and no build setting to change.

What diagram types does Mermaid support?

The ones that carry most documentation are flowcharts, sequence diagrams, state diagrams, entity relationship diagrams and gantt charts. Mermaid also covers class diagrams, pie charts, user journeys, mind maps and timelines; the five above are the ones worth learning first because they map onto things documentation actually has to explain.

Are Mermaid diagrams good for accessibility?

Better than an image of a diagram, because the source is text and the rendered output is SVG rather than a flat picture. It is not automatic, though: give every diagram a sentence of prose nearby that states its conclusion, so a reader who cannot see it still gets the point rather than a list of node names.

Do Mermaid diagrams survive an export?

Yes. The diagram is text inside your Markdown, so Export source carries it out exactly as you wrote it, and Export site carries the rendered output. There is no separate asset to remember.

Should I use Mermaid or a drawing tool?

Use Mermaid for anything that changes with the software: flows, sequences, lifecycles, data models. Use a drawing tool for a considered illustration that is unlikely to change and where layout is the point — a marketing architecture poster, say. The test is whether someone editing the docs a year from now can fix the picture without opening another application.

Try the free plan instead of reading about it

One site, your own docszero.com subdomain, full-text search and the export button, free forever and without a card. Pro is $19.99 a month when you want your own domain, your own look and the badge gone.

Drag in a folder of Markdown, a zip, a Word document or a PDF
Search, navigation and a 404 page are built for you
Export the built site or the source on every plan, free included

Start for free See what it does