Plandalf

Mermaid

Use Mermaid diagrams for small flows, system relationships, and decision paths.

Mermaid is useful when a flow is clearer as a diagram than a list. Keep diagrams short enough to scan.

Basic example

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

Decision diagram

Use Mermaid when a reader needs to understand branching behavior. For purely linear setup, use Steps instead.

Which component should I use? 
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]
<Mermaid title="Which component should I use?" actions placement="top-right">
```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]
```
</Mermaid>

Sequence diagram

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

Checkout session handoff 
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
<Mermaid title="Checkout session handoff" actions={false}>
```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
```
</Mermaid>

Authoring rules

Mermaid usage

Use for relationshipsflow, sequence, decision

Use diagrams for relationships that become harder to follow as prose or bullets.

Keep it smallscan first

A docs diagram should usually fit in one viewport. Split dense architecture into multiple focused diagrams.

Prefer plain labelsreadable nodes

Use short labels and avoid visual decoration inside Mermaid source. Let the docs theme handle styling.

Normalize pasted sourcetypographic arrows

The renderer normalizes typographic arrows and quotes, but authors should still commit normal Mermaid syntax.

Properties

actionsboolean | autodefault: auto

Show or hide the interactive zoom and pan controls. auto shows controls when the rendered diagram is tall enough to need them.

placementtop-left | top-right | bottom-left | bottom-rightdefault: bottom-right

Position of the interactive controls.

Plandalf extensions

titlestring

Caption shown above the rendered diagram.

class | classNamestring

Adds a class to the figure for rare layout-specific cases.

Tree Show folder structures.
Frames Frame diagrams and media.
Steps Use for linear setup.

Feature detail