Mermaid

1 minute read

A mermaid fence becomes an inline SVG when the site is built. The browser never loads Mermaid: the diagram is already a picture, so it works without JavaScript, prints, and reads as text to an agent. The source stays on the page in a disclosure block, so a reader can copy it or an agent can edit it.

Syntax

A fenced code block tagged mermaid:

```mermaid alt="A request goes from the browser to the server"
flowchart LR
  Browser --> Server

The optional `alt="…"` in the fence meta is the diagram's text alternative. Without it, a leading `%% alt: …` comment in the diagram source is used.

## Options

| Name | Type | Default | What it does |
| --- | --- | --- | --- |
| `alt` | string | the `%% alt:` comment, else empty | The accessible name and `<title>` of the SVG. Put it in the fence meta or as a leading `%% alt: …` comment. |

There are no other options. The fence body is the Mermaid source, and the diagram keeps the block's `data-src` and full source span like every other block.

## Example

```mermaid alt="A request goes from the browser to the server and back"
flowchart LR
  Browser --> Server
  Server --> Browser

A sequence diagram works the same way:

The browser asks the server for a page, and the server answersServerBrowserServerBrowserGET /guide/200 OK
Diagram source
sequenceDiagram
  participant B as Browser
  participant S as Server
  B->>S: GET /guide/
  S-->>B: 200 OK

Notes

  • The diagram is rendered during the build in a short child process, so a complex diagram adds build time but no page weight.
  • Colors come from the theme tokens, so the diagram follows light, dark, and right-to-left pages.
  • When a diagram cannot be rendered, the page keeps the source and shows a short fallback instead of failing the build.
  • The source disclosure keeps the exact Mermaid text for agents; the Markdown twin and llms-full.txt carry the same source.
View Markdown

Use with an agent
View Markdown

Open in