Metanorma: Aequitate Verum

Learning Metanorma

Compiling a Metanorma document

To successfully compile a Metanorma document, the toolchain looks at:

  • Metadata: The title, document flavor, and document type.

  • Syntax: Is the entered AsciiDoc code correct?

  • Dependencies: Are all tools needed to compile the document installed?

  • File references: Are any files referred to by the file being compiled, and is their path entered correctly, for example when you include images (image::PATH[]). Advanced AsciiDoc usage also allows a document to embed other AsciiDoc documents (include::PATH[]), and Metanorma extends this in advanced usage to external data sources.

To compile a Metanorma document:

  1. On the command line, go to the folder where the document you want to compile is located.

  2. Enter the following command:

metanorma document.adoc

With this command you trigger the Metanorma toolchain to:

  • Read the AsciiDoc input

  • Convert it into XML

  • Check the XML against the document model (XML schema)

  • Create HTML, PDF, and DOC output

You can also manipulate the way Metanorma compiles a document by setting flags. Flags are appended to the build command, like this:

Example of a build command with a flag
metanorma document.adoc -x html

You can use the following flags to manipulate the building process:

  • -t: Sets the flavor of the document
    NOTE: Either define the flavor in the metadata using mn-document-class or use -t flavor

  • -x: Sets the output format(s) of the document

  • -o: Enter a path that the output should be saved to.

To see the full list of possible build commands, open the Metanorma help on the command line.

metanorma help compile

Because you will often encounter problems during the compilation process, we’ll cover how to troubleshoot very common errors next.

Start next lesson »