Diagrams

A diagram is a fenced block whose language is mermaid, holding Mermaidsource. The Mermaid Diagram control on the editor toolbar inserts one, and it is worth knowing what that control actually does: inside the editor a diagram is a code block that happens to have mermaid as its language, which is why it behaves like one — you type into it, it does not preview, and the picture only exists once the page is published and a reader opens it.

A mermaid fence

```mermaid
flowchart LR
    Draft[Draft] --> Review{Approved?}
    Review -->|Yes| Publish[Publish]
    Review -->|No| Draft

### How it renders {data-id="q7vod4sb"}

```mermaid {data-id="pd7d4tlk"}
flowchart LR
    Draft[Draft] --> Review{Approved?}
    Review -->|Yes| Publish[Publish]
    Review -->|No| Draft

What the fence produces

A mermaid fence does not become a code block. It becomes <pre class="mermaid"> holding the source with no <code> wrapper and no HTML escaping, because the library needs the characters exactly as you wrote them.

That is the reason <, > and & are safe inside a diagram. An arrow written A --> B, a label written -->|Yes|, an entity relationship written ||--o{ — none of it has to be escaped, and none of it should be. Anything you escape by hand reaches Mermaid escaped and fails to parse.

The language on the fence has to be exactly mermaid once attributes are taken off. A fence opened mermaid flowchart is not a diagram; it is a code block whose language the highlighter will not recognize.

Which diagram types work

The first line of the source selects the type, and every type the bundled Mermaid version supports is available. Every type in the table below renders, and every one of them takes your site’s palette. There is no type you have to avoid, no type that has to be rewritten as a flowchart to be colored, and no exception hiding behind the common ones.

Mermaid’s own documentationis the authority on the syntax of each. Leed does not modify it, so anything that renders in Mermaid’s live editor renders here.

How it renders

sequenceDiagram
    participant Author
    participant CMS
    participant Site
    Author->>CMS: Publish
    CMS->>Site: Commit Leed Markdown
    Site-->>Author: Build finished

stateDiagram-v2
    [*] --> Draft
    Draft --> Scheduled: set a date
    Draft --> Published: publish now
    Scheduled --> Published: the date arrives
    Published --> [*]

Three types behave differently enough to be worth naming, and none of them is broken. C4Context takes its colors from the diagram’s own source, through UpdateElementStyle rather than from a palette. sankey-beta paints from a scheme baked into its renderer. kanban looks unthemed at a glance but is not — its tints are Mermaid’s own color maths run over your accent. All three are covered in theming diagrams.

Attributes

Attributes go on the opening fence, and the permissive shorthand works here: .class, #id and key="value" are all accepted, and they land on the <pre>.

```mermaid {#page-mix}
pie title Pages by type
    "Documentation" : 45
    "Blog posts" : 30
    "API reference" : 25

### How it renders {data-id="kuzgtcu3"}

```mermaid {data-id="o0rko8ka"}
pie title Pages by type
    "Documentation" : 45
    "Blog posts" : 30
    "API reference" : 25

How a diagram is drawn

Nothing about a diagram exists at build time except its source. The build detects that the page contains a pre.mermaid, injects the Mermaid module and your palette into that page’s head, and stops there. The browser does the rest: the library is initialized with the palette for the reader’s current color scheme, and then each <pre class="mermaid"> on the page is rendered and its contents replaced with the finished SVG.

Two consequences show up in ordinary authoring.

One bad diagram does not break the others

The palette is proved separately, before any of your diagrams are drawn, by rendering a two-node throwaway. That is deliberate: it means a broken palette cannot be mistaken for one badly written diagram, and one typo cannot silently strip the colors off everything else on the page.

Diagrams redraw when the reader’s system theme changes

The renderer keeps each diagram’s original source, and listens for prefers-color-scheme changing. A reader who switches their machine from light to dark gets every diagram on the page redrawn in the other palette, immediately, with no reload. You get this without doing anything, and it is why a themed site needs two palettes rather than one that follows the page.

Click to zoom

Every rendered diagram opens in the fullscreen zoom viewer. There is nothing to switch on and no attribute to add — a click anywhere on the diagram opens it, the cursor turns to a magnifier on hover, and the viewer pans and zooms. It is the same viewer images use, but unlike an image — which loses its zoom the moment it is wrapped in a link — a diagram is always zoomable.

The zoomed diagram keeps its colors, because the viewer clones the live SVG into the page rather than exporting it. The one requirement that puts on a site’s own theme is covered in theming diagrams.

Giving diagrams your own colors

A site’s palette reaches Mermaid through two files that change together: static/js/mermaid.theme.json in your content repository for everything a Mermaid theme variable can reach, and tailwind/docs/mermaid.css for the handful of colors no variable reaches. Note the path — static/js/, not static/javascript/; the wrong one produces no error and no theming.

Most values in that file are a plain var(--your-token) pointing back at your own site tokens. Mermaid passes those straight into the SVG it emits and the browser resolves them there, which is why a themed diagram follows the reader’s light and dark modes for free. A few keys cannot be a var() and have to be literal hex.

A bad palette never fails the build. If the file cannot be read the build warns, naming the file and the reason, and the site is built with diagrams unthemed. If the file reads but Mermaid itself rejects a value in it, the rejection is caught in the reader’s browser — before any of your diagrams are drawn, on a throwaway two-node diagram rendered for exactly this purpose — logged to the console, and the palette is dropped whole. Either way the symptom is the same and it is easy to miss: a page that builds, and diagrams quietly wearing Mermaid’s stock colors.

Which keys must be literal, how to derive a categorical scale for your own brand, and the cascade rules for the CSS half all belong to theming diagrams, which is where the whole mechanism is taught rather than summarized.

Page types can switch diagrams off — on blogs only

Diagrams are one of nine formatting features that can be turned off per page type, and they are off by default. Like the rest of that group the switch exists for posts-type page types alone: on a documentation or api page type it is inert everywhere — the API skips the check, the toolbar shows the control, and Settings does not render the toggle block. There is no way to disable diagrams on a documentation set, and no hidden control to hunt for.

On a posts-type page type the gate applies to API and MCP writes as well as the toolbar, and rejects with a 400 that names the feature:

This page type does not allow: diagrams (mermaid). Allowed formatting features: code blocks.

Note what that message tells you: a mermaid fence is gated by diagrams, while every other fence is gated by code blocks. Formatting by page type covers the rest of the switches.

A mermaid fence is one of the two fence languages that are not code — the other is math, on the math page — and everything general about fences is on code blocks.