Notes and Admonitions

General

Admonition blocks are typically inserted into the main content of a document providing guidance or request readers to exercise caution.

Types of admonitions

Metanorma supports the following admonition types:

NOTE: Informative guidance.
TIP: Useful information.
EDITOR: Editor's notes that will appear in a draft document.
IMPORTANT: Important information on the application of the document.
WARNING: Information that includes safety concerns.
CAUTION: Information that the reader must be aware.
TODO: Author's or editor's internal notes, not rendered.

The following types of admonitions require an atypical syntax for access:

DANGER: Information that can lead to safety concerns if not covered.
SAFETY PRECAUTION: Information that relates to safety precautions.

Note

Typical AsciiDoc only supports NOTE, TIP, IMPORTANT, CAUTION and WARNING.

In addition, the following types are recognised by specifying [type=...] as a block attribute on one of the latter four built-in admonition types in block mode (other than NOTE):

statement: typographically separate statements in mathematics, such as propositions, proofs, or theorems.
editorial: annotation by document editors, intended for all readers of the document and not just its authors.
box: box element, intended as standalone sidebar which can be referenced from within the document.

[TIP,type=box]
====
This is a box
====

Other types can also be entered.

Specifying admonitions

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 admonition type in all caps and a colon and write your admonition.

Example for a single paragraph noteadoc

NOTE: Advice on when to use which admonition type is specified in ANSI Z535.6.

Warning

Single paragraph admonitions are only guaranteed to be recognised if they are natively supported by AsciiDoc: NOTE, TIP, IMPORTANT, CAUTION and WARNING. DANGER and SAFETY PRECAUTION are not recognised as single paragraph admonitions. EDITOR and TODO are recognised, but only as paragraphs directly under a section header: AsciiDoc limitations mean that they will not be recognised in other contexts, e.g. within table cells.

Block admonitions

The syntax for a block admonition is as follows.

[NOTE] <1>
==== <2>
Content of the admonition block. <3>
Unlike an admonition paragraph, it may contain any AsciiDoc content.
==== <4>

Example of specifying other types of admonitions

== General requirements
[NOTE]
====
This is just a note providing guidance.
====
[IMPORTANT]
====
This is an important message.
====
== Safety requirements
[WARNING]
====
This important notice applies to safety concerns.
====
[CAUTION]
====
This notice must not be ignored.
====

Specifying DANGER and SAFETY

If the admonitions “Danger” and “Safety Precautions” are needed, they should be indicated through a type attribute, which will override the admonition type appearing.

The type value is matched case-insensitively against the admonition labels defined in the i18n internationalization dictionary; the predefined keys are danger and safety precautions. Apart from case, the value must match the dictionary key exactly: type=Safety Precautions matches the predefined safety precautions label, but type=Safety Precaution (singular) does not, and no admonition label will be rendered for it. Additional admonition types can be supported by adding entries under admonition in the i18n dictionary.

.Example of specifying Danger and Safety Precautions messages

Example

[type=Danger]
CAUTION: Do not perform maintenance tasks while the machine is still operating.
[WARNING,type=Safety Precautions]
====
This is a safety precaution
spanning multiple-blocks.
====

Folding notes

General

Notes that are not at the end of a clause are folded into the preceding block, if that block is not delimited (so that the user could not choose to include or exclude a note).

That is, notes immediately following these block types are automatically folded into the preceding element:

list
formula
figure
table

Prevent folding

To prevent a note from folding into the preceding block, add the attribute keep-separate to the note metanorma-standoc ≥ v1.3.29.

Note

Extended to apply to tables metanorma-standoc ≥ v1.10.6.

* A
* B
* C
[NOTE,keep-separate=true]
====
Note not folded into its preceding block
====

Without the keep-separate=true markup, the note would be attached to the list, and numbered accordingly.

[NOTE]
This note will be folded in the preceding block.
NOTE: This one too.

Notes may be given a type through the attribute type metanorma-standoc ≥ v1.4.1.

[NOTE,type=bibliographic]
====
Bibliographic note
====

Explicitly-defined terminology entry notes

Normally, notes are only tagged as term notes when they appear in the context of a terms section.

Rarely, term notes need to be presented in isolation, including in ISO Amendments or Technical Corrigenda.

To achieve that, mark the note up with %termnote metanorma-standoc ≥ v2.1.2.

[NOTE%termnote]
====
Bibliographic note
====

Whole document admonitions

Admonitions (“NOTE”, “IMPORTANT”, “WARNING”, “CAUTION” etc.) in the document body (i.e. within a main body clause) can be stated to apply to the entire document by moving them to the start of the document body, before the main sequence of clauses.

This can be done by giving them the attribute beforeclauses=true metanorma-standoc ≥ v1.3.30.

== Scope
[IMPORTANT,beforeclauses=true]
====
This important notice applies to the entire document.
====
My scope text...

Preface admonitions

Admonitions in the document prefaces (including in the Foreword) can be stated to apply to the entire preface by moving them to the start of the preface, before the Foreword. This can be done by giving them the same attribute beforeclauses=true metanorma-standoc ≥ v1.5.2.

= Document title
:document-attribute: XXXX
[IMPORTANT,beforeclauses=true]
====
This important notice applies to the entire document.
====
== Foreword
My foreword text...

Cover page admonitions

An admonition in the document prefaces can instead be flagged to be rendered on the cover page of the document, through coverpage=true metanorma-standoc ≥ v2.0.8.

= Document title
:document-attribute: XXXX
[IMPORTANT,coverpage=true]
====
This important notice appears on the cover page.
====
== Foreword
My foreword text...

Normally, the label of the type of admonition (NOTE, IMPORTANT, etc) is inserted at the start of the admonition in rendering. This may not be desirable, especially for coverpage admonitions.

Inserting the admonition type is suppressed through notag=true metanorma-standoc ≥ v2.0.8.

= Document title
:document-attribute: XXXX
[IMPORTANT,coverpage=true,notag=true]
====
This important notice appears on the cover page.
====
== Foreword
My foreword text...

Explicitly-defined terminology entry notes

Normally, notes are only tagged as term notes when they appear in the context of a terms section.

Rarely, term notes need to be presented in isolation, including in ISO Amendments or Technical Corrigenda.

To achieve that, mark the note up with %termnote metanorma-standoc ≥ v2.1.2.

[NOTE%termnote]
====
Bibliographic note
====

Edit this page on GitHub →