Mermaid diagrams in Markdown

What Mermaid is

Mermaid is a small language for describing diagrams in text: boxes, arrows and labels written as lines you can type. A tool that supports Mermaid reads those lines and draws the picture. Because the diagram is text, it lives happily inside a Markdown file, can be tracked in Git, and can be written by a program, which is why coding agents reach for it when a plan needs a picture.

In Markdown, a Mermaid diagram is a fenced code block whose language is set to mermaid:

```mermaid
flowchart LR
  A[Draft] --> B[Review]
  B --> C[Ready]
```

That describes a flowchart running left to right with three boxes joined by arrows. In a tool that renders Mermaid you see the boxes; in one that does not, you see the five lines above in a code box.

The diagram types you will meet most

• Flowcharts (flowchart or graph): boxes and arrows for processes and decisions. By far the most common.
• Sequence diagrams (sequenceDiagram): who sends what to whom, in order. Agents use these to explain how parts of a system talk.
• State diagrams (stateDiagram-v2): the states something can be in and how it moves between them.
• Class and entity diagrams: the shape of code or a database.
• Gantt charts, pie charts, mind maps and timelines: less common, but supported by most renderers.

A sequence diagram, for comparison:

```mermaid
sequenceDiagram
  You->>Agent: Plan the feature
  Agent->>You: PLAN.md with open questions
  You->>Agent: Answers in the file
```

Where Mermaid renders

GitHub and GitLab draw Mermaid blocks in their file views. Visual Studio Code needs an extension. Many documentation tools and note apps support it. Nice Markdown draws Mermaid diagrams in its Visual view and includes them when you print or export to PDF. If you are reading a file somewhere that does not render Mermaid, the text is still there; it is just not drawn.

Why coding agents use it

An agent cannot easily draw a picture, but it can write text. Mermaid lets it put an architecture sketch or a workflow into a plan with a few lines, and lets you see the picture without any drawing tool. When the plan changes, the agent edits the lines and the diagram follows. For anyone new to agentic development, Mermaid blocks are one of the things that make a plan file look more intimidating than it is: each one is just a short list of "this connects to that".

Reading a Mermaid block as text

When no renderer is to hand, the text is readable once you know three things. The first line names the diagram type and, for flowcharts, the direction (LR left to right, TD top down). Each later line is one connection: A --> B means an arrow from A to B. Text in brackets after a name is the label shown in the box: A[Draft] is a box called A that displays "Draft". That covers most flowcharts you will meet.

Editing a diagram

Change the text and the picture changes. Adding a step to the flowchart above means adding one line, say C --> D[Published]. In Nice Markdown you can choose Edit on a rendered diagram to change its text, or switch to Source and edit the block there; either way the file stays ordinary Markdown with a Mermaid block in it.

When a diagram will not draw

It shows as a code box

The fence may say ```mermaid with a typo, or the tool does not support Mermaid. Check the spelling first.

It shows an error instead of a picture

Most often a label contains a character Mermaid treats specially: brackets, quotes, a pipe or a semicolon. Put the label in double quotes: A["Review (step 2)"]. The second common cause is an arrow typed with the wrong characters; a flowchart arrow is two dashes and a greater-than sign.

It draws, but the layout is odd

Mermaid lays diagrams out automatically and you have limited control. Switching the direction between LR and TD, or splitting one big diagram into two, usually helps more than fighting the layout.

Common questions

Is Mermaid part of Markdown?

No. Markdown provides the code block; Mermaid is a separate language that some tools recognise inside it. That is why support varies.

Are clickable diagrams supported?

Mermaid allows links and click actions in some diagram types, but many renderers turn them off for safety. Nice Markdown runs Mermaid in its strict mode, so click actions are disabled and labels are shown as plain text.

Can I export the diagram as an image?

Online Mermaid editors can export PNG or SVG. In Nice Markdown the diagram appears in a printed page or exported PDF along with the rest of the document.