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 kinds of directives {admonitions}, however, they are almost always used through their named directives, like {note} or {danger}. 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.

Simpler Admonitions

Admonitions can additionally be styled as simple, and can optionally hide the icon using the icon option of the {myst:directive}admonition.class`.

Removing the icon from an admonition of a certain class allows using a custom emoji for style.

Multiple classes can be combined. See below for an example.

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.