Callouts

Callouts (also called admonitions) draw the eye to information that breaks the flow of the surrounding prose. Use them sparingly — a page full of callouts is a page where nothing is highlighted.

The seven kinds

Each variant has a default icon and accent color that match its intent. Pick the one whose meaning fits your message rather than the one whose color you like.

Note

For neutral asides and clarifications that aren't urgent.

:::note Use note for context Note is the neutral default. Use it for related context, historical notes, or to call out something that's worth knowing but doesn't change what the reader should do. :::

A note without a title. The icon stands on its own.

Tip

For optional shortcuts, best practices, and "here's how to make this easier."

:::tip Save a step Tip is for guidance that's helpful but not required. The reader can ignore it and still succeed. :::

You can also write a tip without a title — handy for one-liners.

Info

For supplementary information that's heavier than a note but lighter than a warning. Often used for "here's how this works under the hood" or "FYI, this default changed in version X."

:::info Behind the scenes Info sits between note and tip in weight. It's useful when you want the reader to remember something for later. :::

Without a title, info works as a slightly more emphatic note.

Warning

For things the reader should be careful with — they're allowed, but easy to misuse.

:::warning Double-check before you commit Warning signals "this isn't dangerous, but it's easy to get wrong." Configuration changes, breaking API changes, and surprising defaults all warrant warnings. :::

A short warning without a title reads as a quick "watch out for this."

Caution

For destructive or irreversible actions. The reader can still proceed — they just need to be sure.

:::caution Read this twice Caution is the step up from warning. It implies "if you do this wrong, you'll lose work or break production." Always pair it with a clear next step. :::

Without a title, caution still reads as a stop-and-think moment.

Danger

For "you almost certainly do not want to do this" — fully destructive operations or known security pitfalls. Reach for danger rarely so it keeps its weight.

:::danger Do not do this in production Danger is the heaviest variant. Reserve it for actions that will delete data, take down a system, or expose a security risk if performed incorrectly. :::

Without a title, danger is a blunt one-line "don't."

Success

For positive confirmations — "you did it" moments at the end of a guide, or callouts of features that solve a common pain point.

:::success You're done Success closes out a tutorial cleanly. It's the visual equivalent of a green checkmark. :::

Without a title, success works as an inline "this is the good outcome."

Mixing markdown inside callouts

Callouts accept full markdown — including lists, links, inline code, and even fenced code blocks. Keep the body focused; if you find yourself writing three paragraphs, the content probably belongs in the main flow.

:::tip A richer example Callouts can contain:

bullet lists
internal links like the quickstart
inline code like bun run start

And short fenced blocks:

bun run db:migrate

Use this power sparingly. The whole point of a callout is that it's brief. :::