Admonitions

Callout boxes that highlight important information. Each type has a distinct color and icon.

Standard Types

Note

Note

This is a note admonition. Use it for supplementary information the reader might find useful.

Tip

Tip

This is a tip admonition. Use it for helpful suggestions and best practices.

Warning

Warning

This is a warning admonition. Use it to alert readers about potential pitfalls.

Danger

Danger

This is a danger admonition. Use it for critical warnings that could cause data loss or security issues.

Important

Important

This is an important admonition. Use it for key information the reader must not miss.

Caution

Caution

This is a caution admonition. Use it for actions that need care but aren’t dangerous.

See Also

See also

Check out the Typography page for text formatting options.

Hint

Hint

This is a hint admonition. Use it for subtle guidance or clues.

Error

Error

This is an error admonition. Use it to document error conditions or common failure modes.

Attention

Attention

This is an attention admonition. Use it when something requires the reader’s immediate focus.

The MyST syntax for any admonition type:

:::{note}
Content goes here with **Markdown** support.
:::

Custom Titles

Override the default title with the admonition directive.

Did You Know?

Sphinx supports over 10 built-in admonition types, and you can create custom ones with any title you like.

Breaking Change

You can also apply a type’s styling to a custom-titled admonition using the :class: option.

The MyST syntax:

:::{admonition} Custom Title
Content here.
:::

:::{admonition} Styled Custom Title
:class: danger
This uses danger styling with a custom title.
:::

Rich Content Inside Admonitions

Admonitions can contain any content — code blocks, lists, tables, and more.

Tip

Here’s a configuration example inside an admonition:

html_theme_options = {
    "accent_color": "#10b981",
    "dark_mode_default": "auto",
}

Key points:

• Use accent_color to customize the primary color

• Set dark_mode_default to "auto" for system preference detection

Nested Admonitions

Admonitions can be nested by increasing the number of colons.

Warning

This is an outer warning.

Tip

This tip is nested inside the warning. Use nested admonitions sparingly — they can be hard to follow.

The MyST syntax (note the extra colon on the outer directive):

::::{warning}
Outer admonition.

:::{tip}
Inner admonition.
:::
::::

Dropdown Admonitions

Use the sphinx-design dropdown directive for collapsible content.

Click to expand

This content is hidden by default. Dropdowns are useful for lengthy details, optional context, or spoilers.

• Item one

• Item two

• Item three

Open by default

This dropdown starts expanded. Use the :open: option when the content is important but you still want the collapsible behavior.

The MyST syntax:

:::{dropdown} Click to expand
Hidden content here.
:::

:::{dropdown} Open by default
:open:
Expanded content here.
:::