MDX Components

Available components for documentation

10 juin 2026

2 min de lecture

MDX Components

Components available in MDX files. Use sparingly. Prefer native markdown.

When to use components

Component	Use for	Not for
Alert	Warnings, breaking changes	General info
Badge	Version numbers, status	Decoration
Card	Grouped info with title	Single paragraphs
CardGrid	2-3 feature cards	More than 3 cards
Chart	Inline data visualizations	Unstructured dumps
Cite	Academic-style references	Inline links
Collapsible	Optional deep-dive	Required reading
Kbd	Keyboard shortcuts	Code or commands
Mermaid	Process flows, diagrams	Simple lists
Steps	Multi-step procedures	Single actions
Tabs	Alternative implementations	Sequential content
Term	Project terminology	Common words

Alert

Warnings and important notices:

tsx

<Alert title="Breaking Change">This API changed in v2.0.</Alert>

Breaking Change

This API changed in v2.0.

Badge

Status labels:

tsx

<Badge color="green">Stable</Badge>
<Badge color="amber">Beta</Badge>
<Badge color="red">Deprecated</Badge>

Stable Beta Deprecated

Colors: green, amber, red, gray

Card

Grouped content:

tsx

<Card title="Quick Start">Get up and running in 5 minutes.</Card>

Quick Start

Get up and running in 5 minutes.

CardGrid

Side-by-side cards (2-3 max):

tsx

<CardGrid>
  <Card title="Users">For users</Card>
  <Card title="Devs">For developers</Card>
</CardGrid>

Users

For users

Devs

For developers

Cite

Academic-style citations that link to the references page:

tsx

The <Cite id="websocket">WebSocket protocol</Cite> enables real-time communication.
The framing spec is in <Cite id="websocket" s="5.2">section 5.2</Cite>.

The WebSocket protocol (6) enables real-time communication. The framing spec is in section 5.2 (6).

Location props

Cite specific sections, pages, or lines. Shown in hover card only:

Prop	Renders as	Example
`s`	§4.1	`<Cite id="rfc" s="4.1">...</Cite>`
`p`	p. 42	`<Cite id="book" p="42-45">...</Cite>`
`line`	line 23	`<Cite id="code" line="23">...</Cite>`
`loc`	(raw string)	`<Cite id="x" loc="Chapter 3">...</Cite>`

Combine multiple: <Cite id="paper" s="3.2" p="15">...</Cite> renders as "§3.2, p. 15"

Archived references

References can have screenshots shown in hover cards and on the References page. Use .withArchive() in src/content/references.ts and place images in src/content/docs/images/references/:

import { websocketImg } from "./docs/images/references";
 
websocket: ref("I. Fette, A. Melnikov", "The WebSocket Protocol", "RFC 6455, IETF", 2011)
  .url("https://datatracker.ietf.org/doc/html/rfc6455")
  .withArchive(websocketImg, "2024-12-15"),

Citations must have a corresponding entry in src/content/references.ts.

Collapsible

Optional detail:

tsx

<Collapsible title="Advanced options">
  Additional configuration details...
</Collapsible>

Kbd

Keyboard shortcuts only:

tsx

Press <Kbd>Ctrl</Kbd> + <Kbd>S</Kbd> to save.

Press Ctrl + S to save.

Mermaid

Diagrams with tabs showing both the rendered output and source code. Use standard markdown code blocks:

tsx

```mermaid
flowchart LR
    A[Input] --> B[Process] --> C[Output]
```;

Supported: flowchart, sequenceDiagram, stateDiagram-v2

Charts

Charts can be rendered directly from MDX and wrapped in a numbered figure block:

tsx

<Figure id="mdx-queue-depth-trend">
  <Chart
    type="line"
    data={[
      { x: 0, y: 14 },
      { x: 1, y: 18 },
      { x: 2, y: 22 },
      { x: 3, y: 29 },
    ]}
  />
</Figure>

Use type="line" | "bar" | "area" | "pie" | "distribution" to select the chart renderer. line and distribution use the same analysis popover + overlay stats used in simulation result charts.

Steps

Multi-step procedures:

tsx

<Steps>
  <Step step={1} title="Install">
    Run npm install.
  </Step>
  <Step step={2} title="Configure">
    Edit the config file.
  </Step>
  <Step step={3} title="Run">
    Start the server.
  </Step>
</Steps>

Install

Run npm install.

Configure

Edit the config file.

Run

Start the server.

Tabs

Alternative implementations:

tsx

<Tabs>
  <TabList>
    <TabTrigger value="npm">npm</TabTrigger>
    <TabTrigger value="pnpm">pnpm</TabTrigger>
  </TabList>
  <TabContent value="npm">npm install wowlab</TabContent>
  <TabContent value="pnpm">pnpm add wowlab</TabContent>
</Tabs>

Term

Project-specific terminology with hover definitions:

tsx

Our Centrifugo instance is called <Term id="beacon" />.
You can also use custom text: <Term id="beacon">the Beacon server</Term>.

Our Centrifugo instance is called beacon. You can also use custom text: the Beacon server.

Terms must have a corresponding entry in src/content/terms.ts:

export const terms: Record<string, Term> = {
  beacon: term(
    "beacon",
    "Beacon",
    "Our Centrifugo-based real-time messaging server...",
    "/dev/docs/networking/realtime-infrastructure", // optional docs link
  ),
};