Callouts
Callouts belong in documentation when context must stay visible beside the content it qualifies. Use feedback components for application state and snackbars for transient confirmation.
Core guidance
Section titled “Core guidance”Lifecycle and compatibility
Section titled “Lifecycle and compatibility”Markdown form
Section titled “Markdown form”The plugin renders Starlight’s aside directives as callouts, in .md and
.mdx alike, so a page written in plain Markdown needs no import. The four
directive names map onto four tones, a directive label becomes the title, and
a directive without one keeps Starlight’s default title.
:::noteDirective asides carry the package surface without an import.:::
:::tip[Pick the directive]Reach for the component only when the tone has no directive name.:::caution is the warning tone and danger is critical; the other six tones
have no directive of their own and stay with the component. Set
markdownCallouts: false on the plugin to leave Starlight’s own asides in
place. The Markdown renditions and llms.txt the plugin writes carry the
directive as authored, because they are built from the source rather than from
the rendered page.
- Keep the title specific enough to scan without reading the body.
- Reserve critical treatment for destructive or blocking consequences.
- Pair compatibility, experimental, and deprecation notices with exact scope.
- Do not stack multiple callouts when ordinary prose or a checklist is clearer.