Admonitions¶
An admonition is a titled box that sets a passage apart from the text around it:
a note, a tip, a warning.
ubCode renders the ten named admonitions of reStructuredText and Sphinx,
and the generic admonition that takes a title of your own,
as real boxes in the editor preview and in its html and pdf builds.
Notes, tips and hints¶
Five admonitions carry supplementary information:
note, tip, hint, important, and Sphinx’s seealso.
Each is given its standard title (Note, Tip, Hint, Important, See also).
Notes, tips and hints
.. note::
Supplementary information the reader may skip.
.. tip::
A better way to do what the text describes.
.. hint::
A nudge towards the answer.
.. important::
Information the reader must not miss.
.. seealso::
Related material the reader may want next.
Note
Supplementary information the reader may skip.
Tip
A better way to do what the text describes.
Hint
A nudge towards the answer.
Important
Information the reader must not miss.
See also
Related material the reader may want next.
```{note}
Supplementary information the reader may skip.
```
```{tip}
A better way to do what the text describes.
```
```{hint}
A nudge towards the answer.
```
```{important}
Information the reader must not miss.
```
```{seealso}
Related material the reader may want next.
```
The MyST form renders live in the MyST notes, tips and hints.
Cautions, warnings and errors¶
Five admonitions warn the reader:
attention, caution, warning, danger, and error.
Each is given its standard title.
Cautions, warnings and errors
.. attention::
Read this before you go on.
.. caution::
Proceed carefully.
.. warning::
This can go wrong.
.. danger::
This can do harm.
.. error::
This went wrong.
Attention
Read this before you go on.
Caution
Proceed carefully.
Warning
This can go wrong.
Danger
This can do harm.
Error
This went wrong.
```{attention}
Read this before you go on.
```
```{caution}
Proceed carefully.
```
```{warning}
This can go wrong.
```
```{danger}
This can do harm.
```
```{error}
This went wrong.
```
The MyST form renders live in the MyST cautions, warnings and errors.
Note
ubCode titles three of these boxes Attention!, Caution! and !DANGER!,
where a Sphinx build titles them Attention, Caution and Danger
(see the structure differences).
A custom admonition¶
The generic admonition takes its title as the argument,
and inline markup in that title is rendered.
Without a :class: its box gets a class made from the title
(admonition-before-you-begin here), which a stylesheet can target.
A custom admonition
.. admonition:: Before you *begin*
Check that the project builds.
Before you begin
Check that the project builds.
```{admonition} Before you *begin*
Check that the project builds.
```
The MyST form renders live in the MyST custom admonition.
Every admonition, named or generic, accepts these options:
:class:Extra CSS classes for the box.
:name:An identifier for the box, which a
:ref:with an explicit title can link to.:collapsible:Makes the box collapsible (see below).
Collapsible admonitions¶
The :collapsible: option turns any admonition into a box the reader can fold:
open (or no value) starts it expanded, closed starts it folded.
Collapsible admonitions
.. note::
:collapsible: closed
Folded until the reader opens it.
.. tip::
:collapsible: open
Open until the reader folds it.
Note
Folded until the reader opens it.
Tip
Open until the reader folds it.
```{note}
:collapsible: closed
Folded until the reader opens it.
```
```{tip}
:collapsible: open
Open until the reader folds it.
```
The MyST form renders live in the MyST collapsible admonitions.
Note
A page in the PDF cannot fold, so ubc build pdf prints every collapsible box open.