Callouts (admonitions)
To highlight a particular block of text that exists slightly apart from the narrative of your page you can use a number of directive kinds like {note}
or {warning}
.
For example, try changing the following directive to a {warning}
:
:::{note} Here is a note, try changing it to a `warning`! :::
The specification calls these kind of directives admonition
, which are generally used through their named directives, like {note}
or {danger}
. Admonitions can have custom classes, icons and hide their children.
#Available admonitions
There is one general {admonition}
directive available, and a number of pre-styled admonitions:
note
important
hint
seealso
tip
attention
caution
warning
danger
error
Try changing the directive type of the admonition below:
:::{tip} Try changing `tip` to `warning`! :::
See below for a demo of each admonition in the default theme.
#Admonition arguments
The base {admonition}
has a single argument, which is the title, you can use markdown in here!
:::{admonition} Admonition *title* Here is an admonition! :::
Note that all other admontions have no arguments, and as in other directives with no arguments content added in this spot will be prepended to the content body.
#Options
- class
- CSS classes to add to your admonition, in addition to the default
admonition
class. The custom CSS class will be first.
For example, you can try adding the name of an admonition to apply those styles.
These classes in the default themes are lowercased without spaces (e.g. seealso
or error
).
You can also add your own class names, and they will be available in HTML.
To see an example, click the HTML
tab in the below demo.
:::{admonition} My title :class: tip My custom admonition that has a `tip` class applied! :::
Note that if you provide conflicting class names, the first one in the list above will be used.
#Admonition Dropdown
You can also hide the body of your admonition blocks so that users must click the header to reveal the contents. This is helpful if you’d like to include some text that isn’t immediately visible to the user. To turn an admonition into a dropdown, add the dropdown
class to them.
:::{note} :class: dropdown This is initially hidden! :::
You can use the dropdown
class in conjunction with {admonition}
directives to include your own titles and stylings. In the example below, we add both a tip
and a dropdown
class.
:::{admonition} Click here! :class: tip dropdown This is initially hidden! :::