Diagrams

Diagrams

Diagrams are Mermaid source in a fenced code block tagged mermaid. The editor shows the picture; the file on disk keeps the text.

```mermaid
flowchart TD
    A[Collect sample] --> B{Contaminated?}
    B -->|yes| C[Discard and re-collect]
    B -->|no| D[Log and label]
```

Every kind Mermaid supports renders: flowchart, sequence, state, class, entity-relationship, gantt, pie and the rest. The picture follows your light or dark theme and re-renders as you edit the source. If Mermaid cannot draw what you wrote, you see the source text rather than a blank hole — so a typo is visible instead of invisible.

Two ways to author one

Graphically — the Diagram Builder

Double-click a diagram, or press Ctrl+Shift+D with the cursor in one, to open the Diagram Builder. With the cursor outside any diagram it starts you a new one.

It is a drag-and-drop canvas beside a live preview:

To…	Do this
Add a node	Add node
Move a node	Drag it
Rename a node	Double-click it
Connect two nodes	Drag from the dot on a node's edge to the other node
Reshape a node	Select it, then pick from Shape
Change a connection	Select it, then pick from Edge
Label a connection	Select it and type in the box at the right of the toolbar
Delete	Select and press Delete
Turn the diagram	Direction — top down, left right, bottom up, right left

Insert writes the diagram back as Mermaid source. Cancel changes nothing — everything you do inside the builder is a draft until you insert it.

As text

Type it in the source panel. Diagram source is not edited inline in the document — the document shows the picture — so the source panel and the builder are the two ways in.

The preview panel shows the diagram your cursor is in, larger, and re-renders as you type. Turn it on from the view controls.

Diagram kinds in the builder

The builder handles the four diagram kinds that are really nodes and arrows:

Kind	Nodes are	Connections are
Flowchart	Steps — rectangle, rounded, stadium, diamond (a decision), circle	Arrow, dotted, thick, or a plain line
State diagram	States, plus the [*] terminal drawn as a filled circle	Transitions
Class diagram	Classes	Inheritance, composition, aggregation, dependency, association, plain link
Entity relationship	Entities	Crow's-foot cardinalities — one-to-one, one-to-many, many-to-one, many-to-many

Two things follow from that table:

• The pickers follow the kind. You cannot put a diamond in a state diagram or a cardinality on a flowchart, because Mermaid has no way to write them.
• Changing the kind keeps your diagram. Every node and edge comes with you; only what the new kind cannot express is adjusted.

The builder opens on whichever kind the diagram already is.

Entity-relationship diagrams have no direction picker — Mermaid lays them out itself and reads a direction line in one as two more entities, so an ER diagram always flows top-down.

Sequence, gantt and pie diagrams are not node-and-arrow graphs. Write those as text and watch the preview panel.

Where node positions live

Where you drag a node on the canvas is your view of it, not part of the diagram. Mermaid computes the real layout when it draws the picture, so the positions are not saved to the file. What is saved is the structure: the nodes, their labels and shapes, and the connections between them.

Diagrams in output

Diagrams render as pictures in exported HTML and in exported PDF, so a document you send on carries what the editor showed you.

Typing past a diagram

Like a table, a rendered diagram is a block the cursor cannot type past from inside — it holds a picture, not text. The editor always keeps an empty paragraph after one, so you can carry on writing below it.

Next

• Writing and Formatting
• Panels and Layout