Admonitions

Admonitions create styled callout boxes for notes, warnings, tips, and other important information.

Key Terms

Admonition

A styled callout box that draws attention to important information. Available in multiple types (note, warning, tip, danger, etc.) with distinct visual styling.

Callout

Another name for an admonition - a visual box that highlights important content separate from the main text flow.

Syntax

1
2
3

:::{admonition-type} Optional Title
Content with **full markdown** support.
:::

Available Types

Examples

Basic Note

1
2
3

:::{note}
This is a note with **markdown** support.
:::

With Title

1
2
3

:::{warning} Important
This feature requires admin access.
:::

Without Title (Uses Type Name)

1
2
3

:::{tip}
Use this pattern for better performance.
:::

Renders as "Tip" (capitalized type name).

Nested Content

Admonitions support full markdown including nested directives. Use named closers for clarity:

1
2
3
4
5
6
7

:::{note}
Here's a tip:

:::{tip}
Nested admonitions work!
:::
:::{/note}

All Types

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

:::{note} Note
General information
:::

:::{tip} Tip
Helpful suggestion
:::

:::{warning} Warning
Something to be careful about
:::

:::{danger} Danger
Critical warning
:::

:::{error} Error
Error message
:::

:::{info} Info
Informational content
:::

:::{example} Example
Example usage
:::

:::{success} Success
Success message
:::

:::{caution} Caution
Cautionary note
:::

Options

Admonitions support standard directive options:

• :class:- Additional CSS classes
• :id:- Element ID

1
2
3
4
5
6

:::{note} Custom Note
:class: custom-class
:id: my-note

Content here
:::

Rendering

Admonitions render as:

1
2
3
4

<div class="admonition note">
  <p class="admonition-title">Note</p>
  <div>Content here</div>
</div>

Best Practices

1. Use appropriate types: Choose the type that best matches the content's importance
2. Keep titles concise: Short, descriptive titles work best
3. Use sparingly: Too many admonitions can overwhelm readers
4. Nest carefully: Nested admonitions work but can be visually busy