Admonitions#

Admonitions (also known as callouts) highlight a particular block of text, that exists slightly apart from the narrative of your page, such as a note or a warning.

Admonitions are a special case of directive extensions. It is advised to use admonitions with the colon_fence extension, which signify that the content of the block is also MyST Markdown.

:::{tip}
Let's give readers a helpful hint!
:::

Tip

Let’s give readers a helpful hint!

1.  Admonition types#

The following core admonition types are available:

Attention

This is a attention

Caution

This is a caution

Danger

This is a danger

Error

This is a error

Hint

This is a hint

Important

This is a important

Note

This is a note

See also

This is a seealso

Tip

This is a tip

Warning

This is a warning

These admonitions take no argument, but may be specified with options:

class:

A space-separated list of CSS classes to add to the admonition, conforming to the identifier normalization rules.

name:

A reference target for the admonition (see cross-referencing).

:::{tip}
:class: myclass1 myclass2
:name: a-tip-reference
Let's give readers a helpful hint!
:::

[Reference to my tip](#a-tip-reference)

Tip

Let’s give readers a helpful hint!

Reference to my tip

Sphinx also adds a number of additional admonition types, for denoting changes to the documentation, or to the codebase:

:::{versionadded} 1.2.3
Explanation of the new feature.
:::

:::{versionchanged} 1.2.3
Explanation of the change.
:::

:::{deprecated} 1.2.3
Explanation of the deprecation.
:::

New in version 1.2.3: Explanation of the new feature.

Changed in version 1.2.3: Explanation of the change.

Deprecated since version 1.2.3: Explanation of the deprecation.

2.  Admonition titles#

To provide a custom title for an admonition, use the admonition directive. If you also want to style the admonition as one of the core admonition types, you can use the admonition directive with the class option.

:::{admonition} My custom title with *Markdown*!
:class: tip

This is a custom title for a tip admonition.
:::

My custom title with Markdown!

This is a custom title for a tip admonition.

3.  Collapsible admonitions#

The sphinx-togglebutton extension allows you to create collapsible admonitions, by adding a dropdown class to the admonition.

:::{note}
:class: dropdown

This admonition has been collapsed,
meaning you can add longer form content here,
without it taking up too much space on the page.
:::

Note

This admonition has been collapsed, meaning you can add longer form content here, without it taking up too much space on the page.

4.  Other Containers (grids, tabs, cards, etc.)#

Using the colon_fence extension, content block can be wrapped in containers with a custom CSS class.

:::bg-primary
This is a container with a custom CSS class.

- It can contain multiple blocks
:::

This is a container with a custom CSS class.

  • It can contain multiple blocks

Using the sphinx-design extension, it is also possible to create beautiful, screen-size responsive web-components.

:::{card} Card Title
Header
^^^
Card content
+++
Footer
:::

Header

Card Title

Card content

Footer

::::{tab-set}

:::{tab-item} Label1
Content 1
:::

:::{tab-item} Label2
Content 2
:::

::::

Content 1

Content 2