Diagrams

Mermaid’s real barrier is not the feature set, it is remembering the syntax. ForkLeaf gives you a blank canvas to drag on, the source beside it, and an editor that tells you which line is wrong.

Inserting a diagram

1. Press / and choose Diagram, or click Diagram on the toolbar.
2. The studio asks what you are drawing. Choosing a type opens a blank canvas carrying that type’s own shapes, arrows and syntax — a flowchart and an ERD do not want the same palette, and guessing meant starting by deleting the wrong thing.
3. Double-click the canvas to add your first box, or pick a shape from the palette. Prefer to start from something finished? Start from an example has a worked diagram of every type, ready to edit.
4. Press Done or Esc. The diagram appears in your note as a rendered picture.

Click any diagram in a note to reopen the studio.

Editing a diagram in its own tab

Some diagrams are bigger than a dialog. Hover a diagram in a note and choose Open in tab — or press it in the studio’s header — and the same studio opens in a browser tab of its own, which you can move to a second screen and leave open while you write.

The note stays the owner of the text. Every edit in that tab is saved into the note as you make it, the header says so as it happens, and the diagram block in the note shows Editing in another tab with an Edit here link that takes editing back. Nothing is duplicated and there is nothing to sync by hand — it is entirely optional, and clicking a diagram still opens it in the note.

Source and canvas, side by side

Both panes are live views of the same Mermaid string, not two modes you switch between: type a node in the source and it appears on the canvas, drag a box and the source updates under your cursor. Drag the divider to give either one more room, or use the Source and Diagram toggles to hand one of them the whole width.

Six types can be drawn rather than typed: flowcharts, sequence diagrams, class diagrams, state machines, entity-relationship diagrams and mindmaps. For those the right pane offers Canvas and Preview. The rest are charts of numbers and dates that are quicker to write than to drag, so they show the preview and are edited as source — which is what the autocomplete, inline errors and syntax reference are for.

A sequence diagram gets a canvas of its own, because its two axes mean different things: participants are columns you drag sideways, and messages are rows you drag up and down. Reordering a row is what changes the order things happen in. One using a loop, alt or note block opens as source instead, since the canvas has no way to draw those and would drop them on the first edit.

Working on the canvas

The diagram types

The template gallery is grouped by what you are trying to show rather than by Mermaid’s internal names, and every card draws a small silhouette of the shape it produces.

The canvas

Available for flowcharts and state diagrams. Drag nodes to move them, drag from a node’s edge handle to draw an arrow, double-click a node to rename it, and press Delete to remove the selection. The Mermaid source is regenerated as you go.

Node positions are preserved in the file as a comment:

flowchart TD
    %% forkleaf:layout a:100,50;b:100,200;c:300,200
    a[Draft] --> b{Review}
    b -->|approve| c[Publish]
    b -->|changes| a

Mermaid ignores %% comments, so the diagram still renders correctly on GitHub and everywhere else — the layout is simply lost to anything that is not ForkLeaf, which is the right trade for keeping the file portable.

The source editor

Everything the visual builder cannot do, you do here. It is not a plain text box:

• Autocomplete that knows the current diagram type, so a sequence diagram suggests sequence keywords.
• Inline errors with the offending line number and a plain-English hint, pinned to the bottom of the preview so they are always on screen.
• Syntax help — a side panel of snippets for the current diagram type. Click one to insert it.
• A forgiving preview. While the source is mid-edit and temporarily invalid, the last diagram that rendered stays on screen instead of flashing an error.

How diagrams are stored

As an ordinary fenced code block. Nothing proprietary, nothing base64-encoded, no external image:

```mermaid
flowchart LR
  A[Keystroke] --> B[(IndexedDB)]
  B --> C{Online?}
  C -->|yes| D[Commit]
  C -->|no| B
```

GitHub renders ```mermaid fences natively, so your diagrams show up when you browse the file there. So does Obsidian, GitLab, and most static site generators.

Exporting diagrams

Diagrams are rendered into HTML, PDF and Word exports as vector graphics. Individual diagrams can be exported as SVG or PNG — see Exporting.