Mermaid

Create flowcharts, sequence diagrams, and other visualizations using Mermaid syntax with automatic rendering.

Write a diagram inside a mermaid code fence and it renders as an SVG:

```mermaid
flowchart LR
  A[Start] --> B{Decision}
  B -->|Yes| C[Action]
  B -->|No| D[End]
```

Diagrams are rendered when your site is built, so no diagramming library is shipped to your readers' browsers. They are drawn with your theme's colors and follow the light and dark toggle automatically.

Supported diagram types

Doccupine renders diagrams with beautiful-mermaid, which supports six diagram types:

Other Mermaid diagram types - including pie, gantt, mindmap, journey, and gitGraph - are not supported. A diagram that cannot be rendered falls back to a plain code block showing its source, and the reason is logged when your site builds. A broken diagram never breaks the page.

Examples

Sequence diagram

Subgraphs

Interactive controls

Diagrams include zoom in and out, pan in four directions, reset the view, and full screen. You can also drag a diagram with your mouse to move it around.

By default the controls appear once a diagram is taller than 120px, since a diagram that already fits does not need them. Use the actions property to decide explicitly. Setting actions={false} turns off the whole interactive layer, including dragging.

Properties

Set properties on the opening fence, after the language:

```mermaid placement="top-left" actions={true}
flowchart LR
  A --> B
```

To hide the controls entirely:

```mermaid actions={false}
flowchart LR
  A --> B
```

Layout

Diagrams are laid out with the ELK engine, which arranges nodes to reduce overlapping edges and keep large diagrams readable. It is always on, so no directive is needed to enable it.

If you are porting diagrams from another tool, a %%{init: ...}%% directive is read as a comment and ignored rather than causing an error.

Theming

Diagram colors come from CSS variables, so they follow your theme and the light/dark toggle without re-rendering. Override any of them in your own CSS to restyle diagrams:

:root {
  --mermaid-bg: var(--color-light);
  --mermaid-fg: var(--color-dark);
  --mermaid-line: var(--color-grayDark);
  --mermaid-accent: var(--color-accent);
  --mermaid-muted: var(--color-grayDark);
  --mermaid-surface: var(--color-grayLight);
  --mermaid-border: var(--color-gray);
}

Syntax reference

For the syntax of each supported diagram type, see the Mermaid documentation. Keep to the six types listed above.