Mermaid

Usage

<Mermaid> renders Mermaid diagrams inline. The library is dynamically imported on first mount, so pages without diagrams pay zero bundle cost.

<Mermaid>
{`graph TD
  A[GitHub push] --> B[Webhook]
  B --> C[Trigger.dev sync job]
  C --> D[Parse MDX]
  D --> E[Upsert pages]
  E --> F[Live on docs site]`}
</Mermaid>

Authoring tips

The Mermaid source goes inside a JSX template literal so the multiline indentation is preserved. You can also pass it via the chart prop if you prefer:

<Mermaid chart={`graph LR
  A --> B
  B --> C`} />

For complex diagrams, the children form is more readable.

Diagram types

Mermaid supports many diagram families. The most common ones in docs:

Flowchart

<Mermaid>
{`graph LR
  A[Start] --> B{Decision}
  B -->|Yes| C[Path A]
  B -->|No| D[Path B]
  C --> E[End]
  D --> E`}
</Mermaid>

Sequence diagram

<Mermaid>
{`sequenceDiagram
  participant U as User
  participant D as Dashboard
  participant S as Supabase
  U->>D: Create project
  D->>S: INSERT projects
  S-->>D: project.id
  D-->>U: Redirect to /projects/:id`}
</Mermaid>

ER diagram

<Mermaid>
{`erDiagram
  ORGANIZATION ||--o{ PROJECT : has
  PROJECT ||--o{ PAGE : contains
  PROJECT ||--o| OPENAPI_SPEC : has
  PROJECT }o--|| ORGANIZATION : belongs-to`}
</Mermaid>

For the full diagram syntax reference, see mermaid.js.org.

Theme integration

The diagram colors are pulled from your --docs-* CSS variables on render — primary, fg, bg, border. When the reader toggles between light and dark mode, the platform watches the data-docs-theme attribute and re-renders the diagram with the new theme tokens automatically.

This means your diagrams always match the surrounding page chrome, no matter how the reader has configured their theme.

Bundle cost

Mermaid is ~600KB minified (~150KB gzipped). The library is dynamically imported on first mount, so:

• Pages without diagrams pay zero Mermaid cost

• Pages with one or more diagrams pay the cost once (the import is module-cached)

This is the right trade-off for docs sites where most pages don't have diagrams.

Error handling

If the Mermaid source has a syntax error, the component renders a red error box with the parser message instead of crashing the page. Useful for catching typos during authoring.

Props

Either chart or children is required. If both are provided, chart wins.