MyST Markdown

Callouts

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}:

:::{tip} Try changing `tip` to `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

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

:::{tip} Admonition _title_ Here is an admonition! :::

Compatibility with GitHub

GitHub markdown transforms blockquotes that start with a bold Note or Warning into a simple admonition (see GitHub). MyST also transforms these blockquotes into the appropriate admonitions with a simple class.

> **Note** This is a note!

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:

::: {.callout-tip} ## Tip with Caption This is an example of a callout with a caption. :::

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} The Title :class: hint This is the body. :::

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.

:::{note} Click Me! 👈 :class: dropdown 👋 This could be a solution to a problem or contain other detailed explanations. :::

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.