MDX blocks reference

Fenced code blocks

Syntax: triple backtick + language identifier.

mermaid

Renders an interactive diagram via Mermaid.js. Dark/light theme-aware.

```mermaid
flowchart LR
  A[Client] --> B[API Gateway]
  B --> C[Service]
  C --> D[(DB)]
```

Supported diagram types: flowchart, sequenceDiagram, classDiagram, erDiagram, gantt, pie, stateDiagram-v2.

Language code blocks

Syntax-highlighted, copy button included.

```ts
const id = endpointId('POST', '/charges')
```

const id = endpointId('POST', '/charges')

Common identifiers:

Identifier	Language
`ts` / `tsx`	TypeScript
`js` / `jsx`	JavaScript
`go`	Go
`bash` / `sh`	Shell
`json`	JSON
`yaml`	YAML
`sql`	SQL
`md` / `mdx`	Markdown

JSX components

Imported automatically via getMDXComponents. No import statement needed in .mdx files.

Callout

<Callout type="info">Default tab is preserved across navigation.</Callout>

<Callout type="warn">Resetting removes all stored state.</Callout>

<Callout type="error">This action cannot be undone.</Callout>

Default tab is preserved across navigation.

Resetting removes all stored state.

This action cannot be undone.

type values: info (default) · warn · error

Steps / Step

Numbered procedure. Each <Step> increments automatically. Use it when order matters and each step is one action the reader performs.

<Steps>
  <Step>Install dependencies: `bun install`</Step>
  <Step>Copy env file: `cp .env.example .env`</Step>
  <Step>Start dev server: `bun dev`</Step>
</Steps>

Install dependencies: bun install

Copy env file: cp .env.example .env

Start dev server: bun dev

Component	Key props	Notes
`<Steps>`	—	Wrapper. Children must be `<Step>`
`<Step>`	—	Numbering is automatic

Labelled steps

Open each <Step> with a bold label, blank line, then the body. The blank line is required — without it MDX joins label and body into one paragraph.

<Steps>
  <Step>
    **Re-export the collection**

    Save to `docs/Wallet.postman_collection.json` at repo root.
  </Step>
  <Step>
    **Preview the diff**

    ```bash
    bun scripts/import-postman.ts --dry-run
    ```
  </Step>
  <Step>
    **Apply**

    <Callout type="warn">Overwrites `content/generated/`. Never edit those files by hand.</Callout>
  </Step>
</Steps>

Re-export the collection

Save to docs/Wallet.postman_collection.json at repo root.

Preview the diff

bun scripts/import-postman.ts --dry-run

Apply

Overwrites content/generated/. Never edit those files by hand.

Any block content works inside a <Step>: code fences, <Callout>, tables, images, nested <Tabs>.

Rules:

Never hand-write 1. or "Step 1" — the counter is generated.
Use a bold label, not ###. A heading inside a <Step> is parsed as a real heading and lands in the page TOC, burying the actual sections.
<Step> is only valid as a direct child of <Steps>.
Unordered facts → bullet list. Alternative paths → <Tabs>. Data moving through a pipeline → <Flow>.

Interactive pipeline diagram (Cloudflare Kumo). Use it for data or control flowing through stages — imports, request lifecycles, build pipelines. Nodes are laid out automatically and connectors are drawn between them.

<Flow>
  <Flow.Node>Wallet.postman_collection.json</Flow.Node>
  <Flow.Node>scripts/import-postman.ts</Flow.Node>
  <Flow.Parallel>
    <Flow.Node>content/generated/</Flow.Node>
    <Flow.Node>content/manual/</Flow.Node>
    <Flow.Node disabled>content/archive/</Flow.Node>
  </Flow.Parallel>
  <Flow.Node>lib/content/load-merged.ts</Flow.Node>
  <Flow.Node>Endpoint page</Flow.Node>
</Flow>

<Flow.Parallel> branches the diagram: every child node sits on its own track between the previous and next node. disabled greys out the connector into a node — good for deprecated or conditional paths.

Vertical orientation

Long labels read better top-to-bottom.

<Flow orientation="vertical" align="center">
  <Flow.Node>POST /charges</Flow.Node>
  <Flow.Node>Validate + idempotency check</Flow.Node>
  <Flow.Node>Provider authorization</Flow.Node>
  <Flow.Node>Webhook dispatch</Flow.Node>
</Flow>

Component	Key props	Notes
`<Flow>`	`orientation` (`"horizontal"` default \| `"vertical"`), `align` (`"start"` default \| `"center"`), `canvas` (bool, default `true`), `padding` (`{ x?: number, y?: number }`, default `{ x: 16, y: 64 }`), `className`	`canvas={false}` drops the pannable wrapper and scrollbars
`<Flow.Node>`	`id` (string), `disabled` (bool), `render` (ReactElement)	`render` fully replaces the default styled box
`<Flow.Parallel>`	`align` (`"end"`)	Branches into concurrent tracks. `align="end"` right-aligns branches to the widest one
`<Flow.List>`	—	Groups nodes into one track without branching
`<Flow.Anchor>`	`type` (`"start"` \| `"end"`), `render` (ReactElement)	Invisible connector attachment point. Omit `type` to act as both

Notes:

Flow is client-only (ssr: false in components/mdx/flow.tsx) and code-split. It does not appear in prerendered HTML, so don't put load-bearing text inside a node — search indexing and no-JS readers won't see it.
Reach for <Flow> over ```mermaid when the shape is a linear pipeline with optional branches, and the diagram should match site theming. Use mermaid for sequence diagrams, ER diagrams, state charts, or anything with cycles and back-edges — Flow has no edge routing.
Keep node labels to a few words. Long labels force horizontal panning.

Tabs / Tab

<Tabs items={['cURL', 'TypeScript', 'Go']}>
  <Tab value="cURL">
    ```bash
    curl -u $KEY: https://api.example.com/v1/charges
    ```
  </Tab>
  <Tab value="TypeScript">
    ```ts
    const charges = await client.charges.list()
    ```
  </Tab>
  <Tab value="Go">
    ```go
    charges, err := client.Charges.List(ctx, nil)
    ```
  </Tab>
</Tabs>

curl -u $KEY: https://api.example.com/v1/charges

items prop = tab labels array. value on <Tab> must match label.

Cards / Card

Link cards in a responsive grid.

<Cards>
  <Card title="Quick guide" href="/docs/get-started/quick-guide" />
  <Card title="Expand" href="/docs/setup/expand" description="Sideload related objects." />
</Cards>

Quick guide

Expand

Sideload related objects.

Prop	Required	Notes
`title`	Yes	Card heading
`href`	Yes	Internal or external URL
`description`	No	Sub-text below title
`icon`	No	React node, renders left of title

Accordions / Accordion

Collapsible FAQ-style content.

<Accordions>
  <Accordion title="What is idempotency?">
    Sending the same request twice produces the same result. Safe to retry.
  </Accordion>
  <Accordion title="How are IDs generated?">
    `nanoid(21)` prefixed by resource type, e.g. `chg_`, `cus_`.
  </Accordion>
</Accordions>

Standard Markdown

Supported natively. No extra setup.

Links

[Anchor text](https://example.com)
[Internal page](/docs/setup/expand)
[Section on same page](#mermaid)

Internal page · Section on same page

Images

![Alt text](/images/diagram.png)

Tables

| Col A | Col B | Col C |
|-------|-------|-------|
| 1     | 2     | 3     |

Inline formatting

Syntax	Result
`bold`	bold
`_italic_`	italic
`code`	`code`
`~~strike~~`	~~strike~~
`> text`	blockquote

Headings

## H2 — appears in page TOC
### H3 — nested in TOC
#### H4 — not in TOC

Files / Folder / File

Renders a file tree. Useful for showing project structure.

<Files>
  <Folder name="app" defaultOpen>
    <File name="layout.tsx" />
    <File name="page.tsx" />
    <Folder name="api">
      <File name="route.ts" />
    </Folder>
  </Folder>
  <File name="package.json" />
</Files>

layout.tsx

page.tsx

package.json

Component	Key props	Notes
`<Files>`	—	Wrapper, no props required
`<Folder>`	`name` (string), `defaultOpen` (bool)	Collapsible. Closed by default
`<File>`	`name` (string)	Leaf node, not collapsible

TypeTable

Manually-written props table. No TypeScript file required. Good for documenting API params, config shapes, or any key→value reference.

<TypeTable
  type={{
    amount: {
      type: 'number',
      description: 'Charge amount in smallest currency unit (e.g. satang).',
    },
    currency: {
      type: 'string',
      description: 'ISO 4217 code.',
      default: '"THB"',
    },
    customerId: {
      type: 'string',
      description: 'Attach charge to existing customer.',
      required: false,
    },
    idempotencyKey: {
      type: 'string',
      description: 'Safe to retry with same key.',
      typeDescriptionLink: 'https://stripe.com/docs/idempotent-requests',
    },
  }}
/>

Prop

Type

Object entry props

Field	Type	Notes
`type`	`ReactNode`	Type string shown in table
`description`	`ReactNode`	Description cell
`default`	`ReactNode`	Default value
`required`	`boolean \| "true" \| "false"`	Shows required badge
`deprecated`	`boolean \| "true" \| "false"`	Shows deprecated badge
`typeDescription`	`ReactNode`	Extra type detail below type cell
`typeDescriptionLink`	`string`	Link on `typeDescription`
`parameters`	array	For function param docs
`returns`	`ReactNode`	For function return docs

Component quick-reference

Block	When to use
```mermaid	Architecture, flow, sequence diagrams
```bash	Shell commands
```json	Request/response examples
`<Callout>`	Non-blocking notices, warnings, errors
`<Steps>`	Ordered setup or migration procedures
`<Flow>`	Linear pipelines with optional parallel branches
`<Tabs>`	Multi-language code samples
`<Cards>`	Navigation hubs, related-links sections
`<Accordions>`	FAQ, collapsible supplementary info
`<Files>` + `<Folder>` + `<File>`	Project/directory structure diagrams
`<TypeTable>`	Manual props/API reference tables

MDX blocks reference

Quick guide

Expand

What is idempotency?

How are IDs generated?

On this page