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.

Note
Important
Hint
See Also
Tip
Attention
Caution
Warning
Danger
Error

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}

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 element
  • simple: 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
MyST MarkdownMyST Markdown
Community-driven tools for the future of technical communication and publication