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 using the {admonition.class} option. 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 ({docs.arg}), which is the admonition title and can use markdown.
If a title argument is not supplied the first node of the {admonition.body} 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 {admonition.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 Jupyter Book 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 Jupyter Book 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 {admonition.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.
To have a dropdown-style admonition start open, add the {admonition.open} option.
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.
