<Callout> highlights a short message in the reading flow. Use a type that matches the message's purpose. The type sets the HTML color and decorative icon, while a visible label carries the meaning in both HTML and Markdown.
Choose a type
Choose a callout type that matches the information readers need to notice.
| Type | Use it for |
|---|---|
note |
Helpful context or a clarification. |
tip |
A practical suggestion that makes a task easier. |
important |
Information readers must notice to complete a task correctly. |
warning |
A possible problem readers can avoid. |
caution |
A higher-risk action or consequence that needs extra care. |
<Callout type="warning">Use a fresh idempotency key for a new payment.</Callout>
Note: The example API is fictional.
Tip: Keep a copy of the response ID for later checks.
Important: Check the selected API version before copying a request.
Warning: A changed idempotency key can create a second payment.
Caution: Review the target environment before deleting data.
Attributes and defaults
Use these attributes to set the callout type and its visible title.
| Attribute | Required | Meaning |
|---|---|---|
type |
No | A built-in or registered type. Omitted with no label defaults to note. |
label |
No | Nonempty literal text that replaces the visible type name. |
Set both when the message needs a more specific label:
<Callout type="warning" label="Before retrying">Reuse the original idempotency key.</Callout>
Before retrying: Reuse the original idempotency key.
A label without a type retains the neutral style used by earlier pages. Its label remains visible in Markdown:
<Callout label="Before you begin">Use a draft page while checking examples.</Callout>
Before you begin: Use a draft page while checking examples.
A bare <Callout> uses the note label and style. Unknown types, unsupported attributes, and empty labels fail the build.
Note: This uses the default note style and label.
Register a type
Add callouts.types to the project config. Each new type needs a label and a tone. The tone can be one of the five built-in values or a name registered in callouts.tones. An optional icon names a Lucide icon in lowercase kebab-case. This site's configuration registers an experiment type with its own laboratory tone:
callouts: { $include: ./config/callouts.yaml }
tones:
laboratory:
line: '#087f8c'
background: '#e9f8f8'
text: '#075c66'
dark:
line: '#3cb9c4'
background: '#0e2a2d'
text: '#8fe3ea'
types:
experiment:
label: Experiment
tone: laboratory
icon: flask-conical
Use the registered name in MDX:
<Callout type="experiment">Try this flow in a test environment first.</Callout>
Experiment: Try this flow in a test environment first.
Each custom tone needs line (left rule), background, and text (label and icon), all as hex colors. Multiple types can share a tone.
A tone's dark block sets the same three colors for dark mode. It is optional on a light-only site. When theme.mode is dark or system, every tone in use needs dark, or the build fails. The build checks each tone against the site's palette in every mode the site shows. Body text, links, and the label need 4.5:1 against the tone's background.
You can also use callouts.tones to replace a built-in tone's colors. The five built-in types have default labels and Lucide icons; you can override their label, tone, or icon in callouts.types. A registered type without an icon displays its label without an icon. Icons are decorative and hidden from assistive technology; the label stays in HTML and Markdown. Invalid names, colors, icons, and definitions fail the build.
HTML, Markdown, and agents
The body accepts ordinary Markdown and supported MDX components. HTML renders a styled blockquote with the visible label and optional icon; Markdown renders a labeled blockquote with the full body. Colors and icons never carry the only meaning, and no browser script is needed. Keep the message short. Use a normal section heading for longer instructions.
The CSS reference lists the color tokens for each type. See the component index for other supported elements.