Admonitions

Admonitions are a great way to include side content, without significantly interrupting the document flow. Sphinx provides several different types of admonitions and allows for the inclusion and nesting of arbitrary content.

Basic Usage

.. note:: This is what the most basic admonitions look like in reStructuredText.

.. note::
   It is *possible* to have multiple paragraphs in the same admonition.

   If you really want, you can even have lists, or code, or tables.

Note

This is what the most basic admonitions look like in reStructuredText.

Note

It is possible to have multiple paragraphs in the same admonition.

If you really want, you can even have lists, or code, or tables.

```{note}
This is what the most basic admonitions look like in Markdown.
```

```{note}
It is *possible* to have multiple paragraphs in the same admonition.

If you really want, you can even have lists, or code, or tables.
```

Note

This is what the most basic admonitions look like in Markdown.

Note

It is possible to have multiple paragraphs in the same admonition.

If you really want, you can even have lists, or code, or tables.

Custom Titles

.. admonition:: Look ma! A custom title.

   It looks different though.

.. admonition:: Another Custom Title
   :class: note

   Maaa! I made it look the same by setting the class.

Look ma! A custom title.

It looks different though.

Another Custom Title

Maaa! I made it look the same by setting the class.

```{admonition} Look ma! A custom title.
It looks different though.
```

```{admonition} Another Custom Title
:class: note

Maaa! I made it look the same by setting the class.
```

Look ma! A custom title.

It looks different though.

Another Custom Title

Maaa! I made it look the same by setting the class.

Supported types

admonition

The one with the custom titles.

It’s got a certain charm to it.

attention

Attention

Climate change is real.

caution

Caution

Cliff ahead: Don’t drive off it.

danger

Danger

Mad scientist at work!

error

Error

Does not compute.

hint

Hint

Insulators insulate, until they are subject to ______ voltage.

important

Important

Tech is not neutral, nor is it apolitical.

note

Note

This is a note.

seealso

See also

Other relevant information.

tip

Tip

25% if the service is good.

todo

This needs the sphinx.ext.todo extension.

Todo

Figure out why this extension uses admonition-todo as the class, instead of using todo (like every other admonition style in Sphinx).

warning

Warning

Reader discretion is strongly advised.

Custom Admonitions

Todo

Describe the CSS variables needed.

Nesting admonitions

.. note::

   You can nest admonitions.

   .. warning::

      But you really should not.

      .. danger::

         It's distracting.

      And can be confusing for the user to understand.

   And, honestly, looks weird.

Note

You can nest admonitions.

Warning

But you really should not.

Danger

It’s distracting.

And can be confusing for the user to understand.

And, honestly, looks weird.

`````{note}
You can nest admonitions.

````{warning}
But you really should not.

```{danger}
It's distracting.
```

And can be confusing for the user to understand.
````

And, honestly, looks weird.
`````

Note

You can nest admonitions.

Warning

But you really should not.

Danger

It’s distracting.

And can be confusing for the user to understand.

And, honestly, looks weird.