Skip To Article

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.

Note
Important
Hint
See Also
Tip
Attention
Caution
Warning
Danger
Error

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

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.

Footnotes
  1. These admonitions are the same as those used in docutils and Sphinx.

MyST MarkdownMyST Markdown
Community-driven tools for the future of technical communication and publication, part of Jupyter.