Using the Mermaid Diagram Block

The Mermaid block turns a few lines of text into a diagram. You describe the boxes and arrows, the editor draws them, and when something changes you edit a line instead of redrawing a picture. It suits anything with a shape to it: a sign-in flow, the order requests travel between systems, the states a ticket moves through.

Reach for Mermaid when the diagram is about structure and you'd rather keep it as text. The layout is worked out for you, so if you need boxes in exact positions, an image is the better fit.

Adding a Mermaid Block

Type / anywhere in an article and pick Diagram (Mermaid). /mermaid, /diagram, /flowchart, /sequence, and /chart all find it.

The block starts with a small two-box flowchart so there's something on screen straight away. Replace it with your own.

What's in the Block

Part	What It's For
Source	The Mermaid text, with line numbers. This is the part you edit
Preview	The drawing, underneath. It redraws a moment after you stop typing
Alt text	A short description for screen readers, set from the button in the block's header
Generate with AI	Writes or changes the diagram from a description. See below

Writing a Diagram

The first line says what kind of diagram it is, and the lines after it describe what's in it. This flowchart:

flowchart LR
            A[Sign in] --> B{Password correct?}
            B -->|Yes| C[Dashboard]
            B -->|No| D[Try again]

Draws like this:

These diagram types are supported:

First Line	Good For
`flowchart`	Processes and decisions. Add `LR` to run left to right, or `TD` for top down
`sequenceDiagram`	Who talks to whom, and in what order
`stateDiagram-v2`	The states something moves through, like a ticket or an order
`classDiagram`	Objects and how they relate
`erDiagram`	Database tables and their relationships
`gantt`	Timelines and schedules
`pie`	Simple proportions
`mindmap`	Ideas branching out from one topic

The full syntax for each one is in the Mermaid documentation.

When a Diagram Won't Draw

A typo in the source doesn't throw your work away. The block shows what's wrong under the source and keeps the last diagram that drew, which is also what readers see until you fix it. Undo works on the source as normal, and the preview follows.

Links and images inside a diagram aren't drawn. If a box needs to take readers somewhere, put the link in the text next to the diagram.

Alt Text

Click Alt text in the block's header and describe what the diagram shows, the way you'd explain it to someone over the phone. A new block starts as just Diagram, which tells a screen reader user nothing, so it's worth the ten seconds.

Generate with AI

Click Generate with AI in the block's header and describe the diagram you want, or what to change about the one that's there ("add a retry step between sign in and the dashboard"). It uses 1 AI credit.

The new diagram replaces the source and the drawing in one step, so a single undo puts the old one back
If AI sends back something that won't draw, your diagram stays as it was
If you edit the diagram while AI is working, your edits win and the result is discarded

The button needs AI features switched on for your account. AI drafting and rewriting can also add Mermaid diagrams to an article when one explains things better than text.

What Readers Get

Readers see a finished drawing, not a script, so it appears instantly and works on every theme. The lines and labels take the text colour of the page around them, which means a diagram looks right in dark mode, in the PDF export, and in the Lighthouse widget without any extra styling.

For the rest of the toolbox see Understanding Block Types, or Shortcuts in the Block Editor for the full keyboard reference.