Callouts, or "admonitions", highlight a particular block of text that exists slightly apart from the narrative of your page, such as a note or a warning.
For example, try changing the following example of a {tip}
admonition to a {warning}
:
In MyST we call these kind of directives admonitions, however, they are almost always used through their named directives, like {note}
or {danger}
. Admonitions can be styled as simple
or as a dropdown
, and can optionally hide the icon. There are ten kinds[1] of admonitions available:
Table 1:Named admonitions that can be used as directives
π΅ note | π attention |
π΅ important | π caution |
π’ hint | π warning |
π’ seealso | π΄ danger |
π’ tip | π΄ error |
See below for a demo of each admonition in the default theme.
Admonition TitlesΒΆ
All admonitions have a single argument, which is the admonition title and can use markdown.
If a title argument is not supplied the first node is used if it is a heading
or a paragraph with fully bold text; otherwise the name of the directive is used (e.g. seealso
becomes See Also
; note
becomes Note
).
Compatibility with GitHub
GitHub markdown transforms blockquotes that start with a bold Note
or text with [!NOTE]
into a simple admonition (see GitHub). This syntax only works for note
, important
or warning
. MyST transforms these blockquotes into the appropriate admonitions with a simple
class.
Compatibility with Pandoc & Quarto
In Quarto/Pandoc markdown admonitions are styled with special classes like {.callout-note}
or {.callout-tip}
).
If you are using JupyterBook or Sphinx documentation, use an {admonition}
directive with the specific class, for example:
Compatibility with Sphinx
In Sphinx, all named admonitions (e.g. {note}
or {tip}
), have no arguments.
If you place content on the first line it will instead be prepended to the admonition body.
If you are using JupyterBook or Sphinx documentation, use an {admonition}
directive with the specific class, for example:
Admonition DropdownΒΆ
To turn an admonition into a dropdown, add the dropdown
class to them.
Dropdown admonitions use the <details>
HTML element (meaning they also will work without Javascript!),
and they can be helpful when including text that shouldn't immediately visible to your readers.
You can also use a {dropdown}
{dropdown}
You can also use a {dropdown}
directive, which provides a more compact writing experience and is simpler in the displayed style. See Dropdowns for more information.
ReferenceΒΆ
- Arguments (markdown)
The
admonition
requires a single argument that is the title, parsed as markdown.- Options
No options are required
- class (optional, string)
- CSS classes to add to your admonition. Special classes include:
dropdown
: turns the admonition into a<details>
html elementsimple
: an admonition with "simple" styles- the name of an admonition, the first admonition name encountered will be used
- Note that if you provide conflicting class names, the first one in the list above will be used.
- icon (optional, boolean)
- setting icon to false will hide the icon