Mermaid

Usage

The easiest way is a standard code fence with the mermaid language tag. It renders as a diagram automatically:

```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]
```

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]

JSX component

You can also use the <Mermaid> component directly with a template literal or chart prop:

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

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

The code fence syntax is recommended for most cases. Use the JSX form when you need to embed diagrams inside other components (like tabs or accordions).

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.