Admonitions

Reference for admonition directives (note, warning, tip, danger, etc.)

2 min read 452 words

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

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

Available Types

Type Purpose CSS Class
{note} General information admonition note
{tip} Helpful tips admonition tip
{warning} Warnings admonition warning
{caution} Cautions (renders as warning) admonition warning
{danger} Critical warnings admonition danger
{error} Error messages admonition error
{info} Informational content admonition info
{example} Examples admonition example
{success} Success messages admonition success
{seealso} Cross-references and related links admonition seealso

Examples

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

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

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

Renders as "Tip" (capitalized type name).

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

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

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

All Types

:::{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 (renders as warning)
:::

:::{seealso} See Also
- [Related Topic](#)
- [Another Resource](#)
:::

Options

Admonitions support the:class:option for custom styling:

Option Description
:class: Additional CSS classes to apply 
:::{note} Custom Note
:class: highlight bordered

Content here
:::

Rendering

Admonitions render with icons and structured markup:

<div class="admonition note">
  <p class="admonition-title">
    <span class="admonition-icon-wrapper"><!-- SVG icon --></span>
    <span class="admonition-title-text">Note</span>
  </p>
  <p>Content here</p>
</div>

CSS classes follow the pattern admonition {type}. The caution type maps to the warningCSS class.

With custom classes via:class::

<div class="admonition note highlight bordered">
  <!-- ... -->
</div>

Best Practices

  1. Match type to severity: Usenote/tip for helpful info, warning/caution for potential issues, danger/errorfor critical problems
  2. Keep titles concise: Short, descriptive titles (2-4 words) work best
  3. Use sparingly: More than 2-3 admonitions per page can overwhelm readers
  4. Nest carefully: Nested admonitions work but increase visual complexity
  5. Preferseealso for links: Group related links in a dedicated seealsoblock rather than inline