Admonitions

Admonitions are signal words used to catch the reader’s attention, such as “TIP”, “NOTE”, or “WARNING”. There are two ways to declare an admonition: in a single paragraph and as a block.

Single-paragraph admonitions

Start a new line with the signal word in all caps and a colon and write your admonition.

Example for an inline note

NOTE: Advice on when to use which signal word is specified in ANSI Z535.6.

Block admonitions

1. Start with the signal word in all caps enclosed in square brackets.

2. Insert the block delimiter.

3. Insert any AsciiDoc markup that you need.

4. End the block with a block delimiter.

Example for a note block.

[NOTE] (1)
==== (2)
This is an example of an admonition block. (3)

Unlike an admonition paragraph, it may contain any AsciiDoc content.
The style can be any one of the admonition labels:

* NOTE
* TIP
* WARNING
* CAUTION
* IMPORTANT
==== (4)

Metanorma-specific admonitions

Metanorma adds two more signal words: "Safety precautions" and "Danger". Since they are not standard AsciiDoc functionality, you’ll need to mark them with a type attribute like this:

DANGER: Do perform maintenance tasks while the machine is still operating.

Practice time

The code for this exercise is available on GitHub.

The corresponding file is named exercise-2-3-5.adoc

Turn the existing text into admonitions:

• Turn the text in line 22 into an IMPORTANT admonition.

• Turn the text in line 24 into a WARNING admonition.

• Turn the text in lines 26-27 into a NOTE admonition.

Hint

To create admonitions that span several lines, you need to declare a block.

[NOTE]
====
This is a long note.
It contains three lines.
Line three.
====

Great progress so far! Let’s look at code samples in the next lesson.

Start next lesson »