Admonitions

Callout boxes for notes, tips, warnings and cautions -- the six kinds, translated titles, your own title with label=, and when a callout is the wrong tool

An admonition is a box that speaks to the reader directly, outside the main line of the text: "you can skip this", "this is the faster way", "check this before you go on". It is your editorial voice, set apart so that a reader who skims still sees it.

The six kinds

Each kind has its own colour and title. Choose by what the note asks of the reader, from optional to urgent:

Result

Note

Supplementary information a reader can skip without losing the thread.

Tip

A better way to do something.

Important

Information the reader needs to succeed.

Warning

Something that needs attention before proceeding.

Caution

An action with negative consequences.

Callout

A neutral box for anything that just needs visual separation.

Markdown

:::note
Supplementary information a reader can skip without losing the thread.
:::
 
:::tip
A better way to do something.
:::
 
:::important
Information the reader needs to succeed.
:::
 
:::warning
Something that needs attention before proceeding.
:::
 
:::caution
An action with negative consequences.
:::
 
:::callout
A neutral box for anything that just needs visual separation.
:::

Kind	Use it when	Example
`note`	The reader may skip it	A historical remark, an alternative notation
`tip`	There is an easier or better way	A shortcut, a useful identity
`important`	Missing it means failing	A prerequisite, a condition the rest depends on
`warning`	Something commonly goes wrong here	A classic mistake, a case the formula excludes
`caution`	Doing it has a cost that is hard to undo	Deleting data, an irreversible setting
`callout`	None of the above fits	A summary box, a set of instructions

The first five match GitHub's alert types, so a reader who knows GitHub reads them the same way.

Titles

Translated automatically

The title ("Note", "Tip", ...) follows the language of the document, not the reader's interface: in a Russian document :::note is titled Заметка, in German Hinweis, in French Note. You always write the kind in English and never translate it yourself. Titles exist for English, Russian, Spanish, French, German and Chinese; a document in any other language gets the English ones.

Your own title

To replace the title, give the box a label:

Result

Before the exam

Bring a calculator without a graphing mode.

Markdown

:::warning{label="Before the exam"}
Bring a calculator without a graphing mode.
:::

Your words are used exactly as written and are not translated. Write the label in the document's language.
The box keeps its kind's colour, so choose the kind by meaning first and the label second.
label="" removes the title bar and leaves the coloured box.

Square brackets do not set a title on an admonition: in :::note[My title] the bracketed text is dropped. Use label="...".

What goes inside

The body is full Markdown: paragraphs, lists, maths, code and links.

Result

Tip

The substitution $t = tan (x /2)$ turns any rational function of $sin x$ and $cos x$ into a rational function of $t$ :

sin x = \frac{2 t}{1 + t ^{2}}, cos x = \frac{1 - t ^{2}}{1 + t ^{2}}, d x = \frac{2 d t}{1 + t ^{2}} .

Markdown

:::tip
The substitution $t = \tan(x/2)$ turns any rational function of
$\sin x$ and $\cos x$ into a rational function of $t$:
 
$$
\sin x = \frac{2t}{1+t^2}, \qquad \cos x = \frac{1-t^2}{1+t^2}, \qquad dx = \frac{2\,dt}{1+t^2}.
$$
:::

A box inside a box is possible, with more colons on the outer fence (see nesting), but rarely helps: two frames around one sentence make it harder to read, not more noticeable.

When not to use one

For mathematics. A definition, a theorem, a remark as part of the theory are statements: they carry the label a mathematical reader looks for (Theorem., Definition.), take a printed number when you give one, and correspond to the LaTeX environments a document imported from .tex arrives as. An admonition is none of those.
For quoting a source. Someone else's words go in a blockquote.
For hiding a solution. Use a collapsible section or :::solution.
For everything. Admonitions work because they are rare. A page that is half callouts has no callouts: the reader learns to skip the boxes, and the one that mattered goes unread. A good rule is no more than one per screen, and no two in a row.