Markdown cheatsheet · Mermaid diagrams

Mermaid diagrams in markdown

Mermaid turns text inside a ```mermaid code fence into a diagram, but only where the renderer supports it. Here's the syntax, and the support table that explains why yours sometimes shows up as plain code.

Mermaid isn't markdown, and that's the whole point

Mermaid is a separate little language for describing diagrams in text. Markdown doesn't understand it; what happens is that some markdown renderers spot a code block tagged mermaid and hand its contents to the Mermaid engine, which draws the picture. So a Mermaid diagram is a fenced code block that a supporting renderer executes instead of printing.

That one sentence explains every problem people hit with it: where the renderer supports Mermaid you get a diagram, and everywhere else you get the raw code, because to a plain renderer that's all it is.

The syntax

Open a fenced code block, put mermaid as the language, and write the diagram definition inside. A flowchart starts with flowchart (or graph) and a direction: TD top-down, LR left-to-right.

```mermaid
flowchart LR
    A[Start] --> B[Write .md]
    B --> C{Renders?}
    C --> D[Ship it]
    C --> E[Fix syntax]
    E --> B
```

Square brackets make a box, curly braces make a decision diamond, --> is an arrow, and -->|label| puts text on it. The indentation is cosmetic; the arrows carry the structure.

The diagram types

Flowcharts are the common case, but the first keyword picks the type. The full set is large; these are the ones you'll actually reach for:

A sequence diagram, for instance, is a list of who sends what to whom:

```mermaid
sequenceDiagram
    You->>maxdown: type ```mermaid
    maxdown->>You: rendered diagram
```

Where Mermaid actually renders

This is the table worth bookmarking, because "my diagram shows as code" is almost always a support question, not a syntax one.

Why your diagram shows up as a code block

Because you're viewing it somewhere that doesn't run Mermaid. There's nothing wrong with the file: the same .md that shows a picture on GitHub shows the raw flowchart LR ... in a plain text preview. If you need the diagram to survive everywhere, export it to an SVG or PNG and drop that in as a normal image instead.

The mistakes that break it

The fence label has to be exactly mermaid

Not Mermaid, not mmd. A different label means the renderer treats it as an ordinary code block and never calls the engine.

A syntax error shows an error box, not your diagram

Unlike markdown, Mermaid is strict: one malformed line and it renders a red error panel instead of the picture. Build diagrams a few lines at a time so you know which line broke it.

Special characters in node text need quoting

Parentheses, colons and other punctuation inside a label can confuse the parser. Wrap the label in quotes: A["Cost (USD)"].

You forgot the direction

flowchart alone often fails; give it a direction, flowchart TD or flowchart LR.

Common questions

Is Mermaid part of markdown?

No. It's a separate diagram language that certain markdown renderers choose to support inside a code block. Markdown itself has no idea what a flowchart is.

How do I make it work on a site that doesn't support it?

Add a Mermaid plugin to your generator, or render the diagram once and embed the resulting SVG or PNG as an image. The image always works; the live code only works where Mermaid runs.

Can I style the colours?

Yes, with Mermaid's %%{init}%% theme directive or classDef statements, though support for theming varies by host. GitHub, for one, applies its own theme.

What's the difference between Mermaid and PlantUML?

Both turn text into diagrams. Mermaid runs in the browser and is what GitHub and friends adopted; PlantUML is older, Java-based, and rendered server-side. For markdown, Mermaid is the one with native support.

Related syntax

• Code
• Images
• Tables
• What is markdown?
• Full cheatsheet

Updated July 2026 · All markdown guides