Document format

This is a general guidance for authoring Metanorma documents.

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.

Unsupported AsciiDoc features

  • Sidebars (`aside`s) are not supported: they have been repurposed 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 Asciidoctor already supports autonumbering for (such as tables and figures), autonumbering in Metanorma extends to formulas (which are encoded as "stem" blocks) and notes. Autonumbering 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.