Boxes

Use these for important messages or for text that is not part of the narrative flow.

Sphinx provides a series of built-in blocks for marking up common boxes, which in Sphinx are called admonitions. The ten default admonitions are:

• note for notes,

• hint, tip and seealso for guidance,

• attention, important, caution and warning for warnings,

• danger and error for critical messages.

All admonitions are created using the following syntax, where name is replaced by the name of the admonition:

:::{name}
Text.
:::

Notes

Note

Admonitions are also called callouts.

Guidance

Hint

This admonition looks like a tip, only the title changes. It could be used in SAQs.

Tip

Agree and document with your team which admonitions to use and for what. Some may be just used during production and others will be student-facing. Avoid using admonitions with the same colour and icon for the same audience, e.g. use hints for students and tips during production, but not both for students.

See also

This could refer to external material or material in another module.

Warnings

The generated PDF uses different icons and colours for some of these admonitions, making them all distinguishable.

Attention

Listen carefully, I shall say this only once…

Important

This looks like the attention admonition, only the title changes.

Caution

Use admonitions sparingly and consistently. Otherwise they overwhelm and confuse the reader.

Warning

This looks like a caution, except for the title.

Critical

The generated PDF uses a different icon for danger.

Danger

This could be used to highlight poor practices that may lead to extra work or wrong results.

Error

This could be used to illustrate typical errors or misconceptions.

Dropdown admonitions

Admonitions can also be set up to only show the title, with the content only revealed when the user clicks on the Click to show button. To enable this, set the :class: dropdown option:

:::{name}
:class: dropdown

Content...
:::

For example, using the note admonition:

:::{note}
:class: dropdown
Thomson: This is a long note...

Thompson: To be precise, it is a whole note.
:::

produces the following interactive behaviour:

Note

Thomson: This is a long note…

Thompson: To be precise, it is a whole note.

For non-interactive outputs, such as PDFs and Word documents, the content is always visible.