Diagrams

Mermaid is enabled for every site, so a fenced mermaid block renders as a diagram with no per-site setup. The palette follows the page's color mode.

See Writing content for examples you can copy.

Captions and anchors

The fence line takes two keys, both optional and both quoted:

```mermaid title="How a page reaches the reader" id="serving-a-page"
sequenceDiagram
  Reader ->> vdoc: opens the page
  vdoc -->> Reader: rendered page
```

Key	What it does
title	Shown as the caption under the diagram, and in the full-screen window
id	The anchor, so a link anywhere on the site can point at the diagram

Anything else on that line is ignored, which keeps the fence valid Markdown everywhere else. GitHub renders a mermaid fence itself and reads only the first word as the language.

Link to a diagram the way you link to a heading:

See [how a page reaches the reader](02-writing-content.mdx#serving-a-page).

The anchor is registered with Docusaurus, so onBrokenAnchors covers it: a link to a diagram whose id was renamed or removed fails the build. Diagrams are not numbered, deliberately. A written reference says what it points at and never goes stale when a diagram is inserted above it.

The viewer

Every diagram is framed, centered in the column and sits in a viewer, so a large one is readable without leaving the page. Click a diagram to open it full screen - that is what the pointer over it means. Escape closes the window again, as does a click outside the diagram.

Hovering a diagram also reveals a toolbar in its top right corner:

Control	What it does
Zoom in, out	One step per click, between half size and eight times
Reset view	Back to the starting scale and position
Open full screen	The same diagram in a window-sized dialog

The same thing without the toolbar:

Gesture	What it does
Ctrl or Cmd with the wheel	Zoom, without zooming the page
Shift with the wheel	Pan, without scrolling the page
Drag, or pinch on a touch screen	Pan, and zoom
Double-click	Reset the view

A bare wheel scrolls the page, so scrolling past a diagram never gets caught in it. Panning, by drag or by shifted wheel, starts once the diagram is zoomed in; below that it is fully in view and there is nothing to pan to. From then on the pointer becomes a hand, a click belongs to the drag it ends, and double-click resets the view.

A diagram takes the keyboard while it has focus, which the full-screen window has from the moment it opens, and a diagram in the page has once you tab to it:

Key	What it does
Ctrl or Cmd +	Zoom in
Ctrl or Cmd -	Zoom out
Ctrl or Cmd 0	Reset

These are the browser's own zoom shortcuts, so a diagram only claims them while it holds focus. Anywhere else they zoom the page as usual.

Scale and position survive a switch between light and dark mode. Closing the full-screen window resets the diagram in the page behind it, so you come back to the page you left.

The viewer is not configurable, and there is nothing to enable. A site that wants a different one can swizzle @theme/Mermaid.

Rendered in the browser

Mermaid draws in the browser, so the server-rendered HTML for a diagram is empty and fills in after hydration. An empty <div> in the built output is expected. The toolbar around it is server rendered and is there from the start.