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.


.. 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.


This is from reStructuredText.

注解

This is what the most basic admonitions look like.

注解

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

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

This is from reStructuredText.

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

```{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.
```

This is from Markdown.

注解

This is what the most basic admonitions look like.

注解

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

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

This is from Markdown.

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

注意

Climate change is real.

caution

小心

Cliff ahead: Don’t drive off it.

danger

危险

Mad scientist at work!

error

错误

Does not compute.

hint

提示

Insulators insulate, until they are subject to ______ voltage.

important

重要

Tech is not neutral, nor is it apolitical.

note

注解

This is a note.

seealso

参见

Other relevant information.

tip

小技巧

25% if the service is good.

todo

This needs the sphinx.ext.todo extension.

待处理

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

warning

警告

Reader discretion is strongly advised.

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.

注解

You can nest admonitions.

警告

But you really should not.

危险

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.
`````

注解

You can nest admonitions.

警告

But you really should not.

危险

It’s distracting.

And can be confusing for the user to understand.

And, honestly, looks weird.

Custom Admonitions

It is possible to define custom admonitions for use with Furo. This is done by including custom CSS in the site.

Borrowing from the equivalent example for mkdocs-material, the CSS would be something like:

:root {
  --icon--pied-piper: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><path d="M244 246c-3.2-2-6.3-2.9-10.1-2.9-6.6 0-12.6 3.2-19.3 3.7l1.7 4.9zm135.9 197.9c-19 0-64.1 9.5-79.9 19.8l6.9 45.1c35.7 6.1 70.1 3.6 106-9.8-4.8-10-23.5-55.1-33-55.1zM340.8 177c6.6 2.8 11.5 9.2 22.7 22.1 2-1.4 7.5-5.2 7.5-8.6 0-4.9-11.8-13.2-13.2-23 11.2-5.7 25.2-6 37.6-8.9 68.1-16.4 116.3-52.9 146.8-116.7C548.3 29.3 554 16.1 554.6 2l-2 2.6c-28.4 50-33 63.2-81.3 100-31.9 24.4-69.2 40.2-106.6 54.6l-6.3-.3v-21.8c-19.6 1.6-19.7-14.6-31.6-23-18.7 20.6-31.6 40.8-58.9 51.1-12.7 4.8-19.6 10-25.9 21.8 34.9-16.4 91.2-13.5 98.8-10zM555.5 0l-.6 1.1-.3.9.6-.6zm-59.2 382.1c-33.9-56.9-75.3-118.4-150-115.5l-.3-6c-1.1-13.5 32.8 3.2 35.1-31l-14.4 7.2c-19.8-45.7-8.6-54.3-65.5-54.3-14.7 0-26.7 1.7-41.4 4.6 2.9 18.6 2.2 36.7-10.9 50.3l19.5 5.5c-1.7 3.2-2.9 6.3-2.9 9.8 0 21 42.8 2.9 42.8 33.6 0 18.4-36.8 60.1-54.9 60.1-8 0-53.7-50-53.4-60.1l.3-4.6 52.3-11.5c13-2.6 12.3-22.7-2.9-22.7-3.7 0-43.1 9.2-49.4 10.6-2-5.2-7.5-14.1-13.8-14.1-3.2 0-6.3 3.2-9.5 4-9.2 2.6-31 2.9-21.5 20.1L15.9 298.5c-5.5 1.1-8.9 6.3-8.9 11.8 0 6 5.5 10.9 11.5 10.9 8 0 131.3-28.4 147.4-32.2 2.6 3.2 4.6 6.3 7.8 8.6 20.1 14.4 59.8 85.9 76.4 85.9 24.1 0 58-22.4 71.3-41.9 3.2-4.3 6.9-7.5 12.4-6.9.6 13.8-31.6 34.2-33 43.7-1.4 10.2-1 35.2-.3 41.1 26.7 8.1 52-3.6 77.9-2.9 4.3-21 10.6-41.9 9.8-63.5l-.3-9.5c-1.4-34.2-10.9-38.5-34.8-58.6-1.1-1.1-2.6-2.6-3.7-4 2.2-1.4 1.1-1 4.6-1.7 88.5 0 56.3 183.6 111.5 229.9 33.1-15 72.5-27.9 103.5-47.2-29-25.6-52.6-45.7-72.7-79.9zm-196.2 46.1v27.2l11.8-3.4-2.9-23.8zm-68.7-150.4l24.1 61.2 21-13.8-31.3-50.9zm84.4 154.9l2 12.4c9-1.5 58.4-6.6 58.4-14.1 0-1.4-.6-3.2-.9-4.6-26.8 0-36.9 3.8-59.5 6.3z"/></svg>')
}
.admonition.pied-piper {
  border-color: rgb(43, 155, 70);
}
.admonition.pied-piper > .admonition-title {
  background-color: rgba(43, 155, 70, 0.1);
  border-color: rgb(43, 155, 70);
}
.admonition.pied-piper > .admonition-title::before {
  background-color: rgb(43, 155, 70);
  -webkit-mask-image: var(--icon--pied-piper);
          mask-image: var(--icon--pied-piper);
}

With this, you can now use this by setting the :class: pied-piper on an admonition:

.. admonition:: Pied Piper
   :class: pied-piper

   This is neat, right?


This is from reStructuredText.

Pied Piper

This is neat, right?

This is from reStructuredText.

```{admonition} Pied Piper
:class: pied-piper

This is neat, right?
```

This is from Markdown.

Pied Piper

This is neat, right?

This is from Markdown.