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 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 {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.
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.
