Metanorma: Aequitate Verum

Metanorma AsciiDoc

This is a general guidance for authoring Metanorma documents using Metanorma AsciiDoc.

Since Metanorma uses AsciiDoc markup (see Approach for technical background), this section details the specific ways in which Metanorma interprets AsciiDoc markup, as well as custom markup directives.

This section applies across most of the officially supported flavors of Metanorma. If you are using one of those flavors, be sure to also check out guidelines for your flavor.

Basic AsciiDoc syntax

Metanorma AsciiDoc is based on the AsciiDoc syntax used by Asciidoctor.

Please refer to the Asciidoctor manual for general markup mechanisms offered in typical AsciiDoc.

Unsupported AsciiDoc features

  • Sidebars (asides) are not supported. Instead, they are used for reviewer comments.

  • Page breaks (thematic break) are not supported.

  • ASCII art/preformatted text (literal) are not supported in most Metanorma flavors.


In addition to the blocks that typical AsciiDoc already supports auto-numbering for (such as tables and figures), auto-numbering in Metanorma extends to formulas (which are encoded as stem blocks) and notes.

Auto-numbering is applied in the conversion from Metanorma XML to output formats (isodoc); by default it restarts for each annex, but is continuous within the main body of text.