Metanorma: Aequitate Verum

Author's documentation

Introduction to Metanorma AsciiDoc

tag::tutorial[]

Metanorma documents are written in AsciiDoc, a markup language that annotates text with processing instructions for layout.

Since AsciiDoc only consists of plain text, you can use any editor to create AsciiDoc files (.adoc files).

AsciiDoc is very similar to Markdown or Wiki formatting but provides more precise markup for creating text documents, for example to create a bibliography section or an index.

Because Metanorma fulfills the markup requirements of SDOs, Metanorma extends plain AsciiDoc. This version of AsciiDoc is called Metanorma AsciiDoc.

An AsciiDoc document consists of different levels of granularity:

  • The document head (also called the header)

  • Sections

  • Blocks

  • Inline markup end::tutorial[]

The Asciidoctor manual provides ample information about the general markup mechanisms of typical AsciiDoc.

Unsupported AsciiDoc features

While Metanorma mostly adds functionality to the AsciiDoc markup language, there are also some mechanisms, that Metanorma does not support:

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

  • Page breaks (thematic break) are only supported in select flavors.

  • ASCII art/preformatted text (literal) are only supported in select flavors.