Diagrams

A diagram is a block you can drop anywhere in a page to draw a flow, an architecture, or a relationship. You write it in Mermaid and the editor renders it to a clean diagram in your spec's colours — text source in the file, picture on the page. It replaces fiddly ASCII art that breaks the moment you add a node.

Inserting one

Run /diagram from the slash menu. A two-column editor opens: on the left you pick a format, give the diagram an optional caption, and type the source; on the right a live preview renders as you type (refreshing a fraction of a second after you pause). If the source has a mistake, the preview shows the error and the line it's on, so you can fix it before inserting.

In your markdown the diagram is a single block with the source inside it:

<diagram format="mermaid" caption="Request flow">
graph TD
  A[Client] --> B[API] --> C[(Database)]
</diagram>

Editing and removing

Alt-click (option-click on a Mac) or double-click a rendered diagram to reopen that two-column editor with the source filled in. Save updates it, Remove deletes the block (undoable with Ctrl/Cmd+Z), Cancel leaves it untouched.

The full-screen viewer

Big diagrams don't have to be squinted at inline. Hover a rendered diagram and a Maximize button appears in its top-right corner; it opens a full-screen viewer for panning and zooming around the picture.