# Mermaid
Use Mermaid diagrams for small flows, system relationships, and decision paths.
Source: /docs/components/mermaid
Last modified: 2026-06-20
Mermaid is useful when a flow is clearer as a diagram than a list. Keep diagrams short enough to scan.

## Basic example


### Checkout flow

```mermaid

```mermaid title="checkout-flow.mmd"
flowchart LR
  A[Published offer] --> B[Checkout session]
  B --> C[Payment]
  C --> D[Automation]
```

```


````mdx title="mermaid-example.mdx"

### Checkout flow

```mermaid

```mermaid title="checkout-flow.mmd"
flowchart LR
  A[Published offer] --> B[Checkout session]
  B --> C[Payment]
  C --> D[Automation]
```

```

````

## Decision diagram

Use Mermaid when a reader needs to understand branching behavior. For purely linear setup, use [Steps](/docs/components/steps) instead.


### Which component should I use?

```mermaid

```mermaid title="component-choice.mmd"
flowchart TD
  A[Does the reader need to act?] -->|Yes| B[Steps]
  A -->|No| C[Is this a choice?]
  C -->|Implementation option| D[Tabs or CodeGroup]
  C -->|Optional detail| E[Accordion or Expandable]
  C -->|API shape| F[Fields and Examples]
```

```


````mdx title="mermaid-decision.mdx"

### Which component should I use?

```mermaid

```mermaid title="component-choice.mmd"
flowchart TD
  A[Does the reader need to act?] -->|Yes| B[Steps]
  A -->|No| C[Is this a choice?]
  C -->|Implementation option| D[Tabs or CodeGroup]
  C -->|Optional detail| E[Accordion or Expandable]
  C -->|API shape| F[Fields and Examples]
```

```

````

## Sequence diagram

Sequence diagrams work well for API, SDK, webhook, and automation handoffs because each participant stays visible.


### Checkout session handoff

```mermaid

```mermaid title="checkout-session-sequence.mmd"
sequenceDiagram
  participant Site
  participant Plandalf
  participant Stripe
  participant Automation
  Site->>Plandalf: Create checkout session
  Plandalf->>Stripe: Prepare payment
  Stripe-->>Plandalf: Payment result
  Plandalf->>Automation: Purchase event
```

```


````mdx title="mermaid-sequence.mdx"

### Checkout session handoff

```mermaid

```mermaid title="checkout-session-sequence.mmd"
sequenceDiagram
  participant Site
  participant Plandalf
  participant Stripe
  participant Automation
  Site->>Plandalf: Create checkout session
  Plandalf->>Stripe: Prepare payment
  Stripe-->>Plandalf: Payment result
  Plandalf->>Automation: Purchase event
```

```

````

## Authoring rules


### Mermaid usage


- `Use for relationships` (flow, sequence, decision):
    Use diagrams for relationships that become harder to follow as prose or bullets.


- `Keep it small` (scan first):
    A docs diagram should usually fit in one viewport. Split dense architecture into multiple focused diagrams.


- `Prefer plain labels` (readable nodes):
    Use short labels and avoid visual decoration inside Mermaid source. Let the docs theme handle styling.


- `Normalize pasted source` (typographic arrows):
    The renderer normalizes typographic arrows and quotes, but authors should still commit normal Mermaid syntax.


## Properties


- `actions` (boolean | auto; default: auto):
  Show or hide the interactive zoom and pan controls. `auto` shows controls when the rendered diagram is tall enough to need them.


- `placement` (top-left | top-right | bottom-left | bottom-right; default: bottom-right):
  Position of the interactive controls.


## Plandalf extensions


- `title` (string):
  Caption shown above the rendered diagram.


- `class | className` (string):
  Adds a class to the figure for rare layout-specific cases.


## Related


  - [Tree](/docs/components/tree): Show folder structures.
  - [Frames](/docs/components/frames): Frame diagrams and media.
  - [Steps](/docs/components/steps): Use for linear setup.