Admonitions

There are certain statements you may want to draw attention to by taking them out of the content’s flow and labeling them with a priority. These are called admonitions. This page introduces you to admonition types AsciiDoc provides, how to add admonitions to your document, and how to enhance them using icons or emoji.

The examples on this page (and in these docs) use a visual theme that differs from the style provided by AsciiDoc processors such as Asciidoctor. The AsciiDoc language does not require that the admonitions be rendered using a particular style. The only requirement is that they be offset from the main text and labeled appropriately according to their admonition type.

Admonition types

The rendered style of an admonition is determined by the assigned type (i.e., name). The AsciiDoc language provides five admonition types represented by the following labels:

  • NOTE

  • TIP

  • IMPORTANT

  • CAUTION

  • WARNING

The label is specified either as the block style or as a special paragraph prefix. The label becomes visible to the reader unless icons are enabled, in which case the icon is shown in its place.

Caution vs. Warning

When choosing the admonition type, you may find yourself getting confused between "caution" and "warning" as these words are often used interchangeably. Here’s a simple rule to help you differentiate the two:

  • Use CAUTION to advise the reader to act carefully (i.e., exercise care).

  • Use WARNING to inform the reader of danger, harm, or consequences that exist.

To find a deeper analysis, see www.differencebetween.com/difference-between-caution-and-vs-warning/.

Admonition syntax

When you want to call attention to a single paragraph, start the first line of the paragraph with the label you want to use. The label must be uppercase and followed by a colon (:).

Example 1. Admonition paragraph syntax
WARNING: Wolpertingers are known to nest in server racks. (1) (2)
Enter at your own risk.
1 The label must be uppercase and immediately followed by a colon (:).
2 Separate the first line of the paragraph from the label by a single space.

The result of Example 1 is displayed below.

Wolpertingers are known to nest in server racks. Enter at your own risk.

When you want to apply an admonition to complex content, set the label as a style attribute on a block. As seen in the next example, admonition labels are commonly set on example blocks. This behavior is referred to as masquerading. The label must be uppercase when set as an attribute on a block.

Example 2. Admonition block syntax
[IMPORTANT] (1)
.Feeding the Werewolves
==== (2)
While werewolves are hardy community members, keep in mind the following dietary concerns:

. They are allergic to cinnamon.
. More than two glasses of orange juice in 24 hours makes them howl in harmony with alarms and sirens.
. Celery makes them sad.
====
1 Set the label in an attribute list on a delimited block. The label must be uppercase.
2 Admonition styles are commonly set on example blocks. Example blocks are delimited by four equal signs (====).

The result of Example 2 is displayed below.

Feeding the Werewolves

While werewolves are hardy community members, keep in mind the following dietary concerns:

  1. They are allergic to cinnamon.

  2. More than two glasses of orange juice in 24 hours makes them howl in harmony with alarms and sirens.

  3. Celery makes them sad.

Enable admonition icons

In the examples above, the admonition is rendered in a callout box with the style label in the gutter. You can replace the textual labels with font icons by setting the icons attribute on the document and assigning it the value font.

Example 3. Admonition paragraph with icons set
= Document Title
:icons: font

WARNING: Wolpertingers are known to nest in server racks.
Enter at your own risk.

Learn more about using Font Awesome or custom icons with admonitions in Font Icons Mode.

Using emoji for admonition icons

If image-based or font-based icons are not available, you can leverage the admonition caption to display an emoji (or any symbol from Unicode) in the place of the admonition label, thus giving you an alternative way to make admonition icons.

If the icons attribute is not set on the document, the admonition label is shown as text (e.g., CAUTION). The text for this label comes from an AsciiDoc attribute. The name of the attribute is <type>-caption, where <type> is the admonition type in lowercase. For example, the attribute for a tip admonition is tip-caption.

Instead of a word, you can assign a Unicode glyph to this attribute:

:tip-caption: šŸ’”

[TIP]
It's possible to use Unicode glyphs as admonition icons.

Here’s the result you get in the HTML:

<td class="icon">
<div class="title">šŸ’”</div>
</td>

Instead of entering the glyph directly, you can enter a character reference instead. However, since you’re defining the character reference in an attribute entry, you (currently) have to disable substitutions on the value.

:tip-caption: pass:[&#128161;]

[TIP]
It's possible to use Unicode glyphs as admonition icons.

On GitHub, the HTML output from the AsciiDoc processor is run through a postprocessing filter that substitutes emoji shortcodes with emoji symbols. That means you can use these shortcodes instead in the value of the attribute:

ifdef::env-github[]
:tip-caption: :bulb:
endif::[]

[TIP]
It's possible to use emojis as admonition icons on GitHub.

When the document is processed through the GitHub interface, the shortcodes get replaced with real emojis. This is the only known way to get admonition icons to work on GitHub.