Metanorma CLI Usage

Usage samples

For a single document:

$ metanorma my-standard-document.adoc

$ metanorma --type iso -x html my-standard-document.adoc

if type and extensions are not defined in the .

See Metanorma CLI Manual for the complete Metanorma CLI command options.

Generate a new Metanorma document using a template (`metanorma new`)

Metanorma CLI allows you to create a new document using an official template, or a user-specified custom template.

To see what options are available under the new command, run metanorma help new.

Generate a new document from an official Metanorma template

The metanorma new command allows you to create a document using templates.

To create a new document using an official template, you simply invoke the command with the mandatory options type and doctype, then Metanorma will find and load the official template to create your document.

By default, the template repository for a certain flavor is located at: https://github.com/metanorma/metanorma-{flavor-name}.

For example, if you want to create a new CalConnect document (type: calconnect) called calconnect-foo-standard, using the standard template type, run the following command:

metanorma new -d standard -t calconnect calconnect-foo-standard

This will create your bare bones document and will also print out all files created during generation.

Most Metanorma flavors provide templates

Generate a new document from a custom Metanorma template repository

The CLI allows using custom or unofficial template repositories, meaning you could also generate a new document using your own custom template.

Metanorma supports two types of template repositories:

Git: a Git repository (local or remote, public or private)
Local: a directory

Once a template repository and a template within is specified, Metanorma will automatically download and generate the new document using your custom template.

For example, if you want to create a new CalConnect document with the following parameters:

Document name: my-custom-calconnect-document
Flavor: calconnect
Doctype: standard
Template: https://gitfoo.com/foobar/mn-templates-foobar (fictitious example)

You could execute the following command to do so:

metanorma new -d standard -t calconnect \
  -l https://gitfoo.com/foobar/mn-templates-foobar my-custom-calconnect-document

When using a local directory:

metanorma new -d standard -t calconnect \
  -l ~/shared/mn-templates my-custom-calconnect-document

Compile a document (`metanorma compile` or just `metanorma`)

The key functionality of this CLI is to allow compilation of a Metanorma document. The command metanorma help compile will display all usage instructions of the compile command shown with available options.

Usage:
  metanorma compile FILENAME [..options]

Options:
  -t, [--type=TYPE]                           # Type of standard to generate
  -x, [--extensions=EXTENSIONS]               # Type of extension to generate per type
  -f, [--format=FORMAT]                       # Format of source file: eg. asciidoc
                                              # Default: asciidoc
  -r, [--require=LIBRARY]                     # Require LIBRARY prior to execution
  -w, [--wrapper], [--no-wrapper]             # Create wrapper folder for HTML output
  -a, [--asciimath], [--no-asciimath]         # Keep Asciimath in XML output instead of
                                              # converting it to MathML
  -d, [--datauriimage], [--no-datauriimage]   # Encode HTML output images as data URIs
  -R, [--relaton=RELATON]                     # Export Relaton XML for document to nominated
                                              # filename
  -e, [--extract=EXTRACT]                     # Export sourcecode fragments from this document
                                              # to nominated directory
  -v, [--version=VERSION]                     # Print version of code (accompanied with -t)
  -L, [--log_messages]                        # Display available log messages
                                              # (accompanied with -t)
  -o, [--output-dir=DIRECTORY]                # Directory to save compiled files
  -S, [--strict], [--no-strict]               # Strict compilation: abort if there are any
                                              # errors
      [--agree-to-terms], [--no-agree-to-terms] # Agree/Disagree with all third-party
                                              # licensing terms presented
                                              # (WARNING: do know what you are agreeing with!)
      [--install-fonts], [--no-install-fonts] # Install required fonts (default: true)
      [--continue-without-fonts],
      [--no-continue-without-fonts]           # Continue processing even when fonts are missing
  -s, [--progress], [--no-progress]           # Show progress for long running tasks

So, let’s put this in use. For example we have a document my-iso-document.adoc and we want to compile this using iso and html as extension, then we can use the following command.

metanorma compile --type iso -x html my-iso-document.adoc
# or just
metanorma --type iso -x html my-iso-document.adoc

This should compile any valid document, but if there are some issues then it will also print those out in the terminal. Currently, the supported flavors are ietf, iso, gb, calconnect, csa, m3d and rsd.

Additional compile options

Data URI images (`--datauriimage`)

Encode all images in HTML output as data URIs instead of external file references.

This creates self-contained HTML files but increases file size.

metanorma compile --type iso -x html --datauriimage my-document.adoc

Output directory (`--output-dir`)

Specify a custom directory where compiled files will be saved.

metanorma compile --type iso -o output/documents my-document.adoc

Strict mode (`--strict`)

Enable strict compilation mode which will abort the compilation if there are any errors.

metanorma compile --type iso --strict my-document.adoc

Font installation options

Control how fonts are handled during compilation:

# Skip font installation
metanorma compile --type iso --no-install-fonts my-document.adoc

# Continue even if fonts are missing
metanorma compile --type iso --continue-without-fonts my-document.adoc

Progress display (`--progress`)

Show progress for long running tasks such as font downloads:

metanorma compile --type iso --progress my-document.adoc

Compile a document collection (`metanorma collection`)

This functionality compiles collections of Metanorma documents. It compiles the individual documents comprising the collection; then it compiles a document acting as a container for those collections. See https://github.com/metanorma/metanorma/wiki/Metanorma-collections, https://github.com/metanorma/metanorma-cli/blob/master/spec/fixtures/collection1.yml

The file argument to the collection command is a Metanorma Collections YAML file, which contains:

Directives on how the collection should be generated
Metadata about the collection
A manifest listing the documents contained in the collection, in nested hierarchy
Content to put at the beginning of the collection container
Content to put at the ending of the collection container

Documents within a collection may cross-reference each other using the syntax * [], (see Issue 57), where mydoc is be the value of docref/identifier corresponding to the target document, as set in the YAML manifest.

The output directory will contain:

The documents referenced in the manifest, with any citations of other documents in the collection resolved, in the output formats requested
If xml or presentation are requested as formats, a concatenated collection.xml and/or collection.presentation.xml file, containing all the documents in the collection.
If html is requested as a format, an index.html HTML page, populated from a provided Liquid template cover page, and linking to all the documents in the manifest.

Usage:
  metanorma collection FILENAME [..options]

Options:
  -x, [--format=FORMATS]                      # Formats to generate
  -w, [--output-folder=FOLDER]                # Directory to save compiled files
  -c, [--coverpage=COVERPAGE]                 # Liquid template for collection cover page
                                              # (currently HTML only)
      [--agree-to-terms], [--no-agree-to-terms] # Agree/Disagree with all third-party
                                              # licensing terms presented
      [--install-fonts], [--no-install-fonts] # Install required fonts (default: true)
      [--continue-without-fonts],
      [--no-continue-without-fonts]           # Continue processing even when fonts are missing
  -S, [--strict], [--no-strict]               # Strict compilation: abort if there are any
                                              # errors
  -s, [--progress], [--no-progress]           # Show progress for long running tasks

Convert documents between formats (`metanorma convert`)

The convert command converts documents between different formats, including:

STS (Standards Tag Suite) XML to Metanorma AsciiDoc
Metanorma XML to STS (ISO, NISO, IEEE flavors)
RFC XML to Metanorma AsciiDoc

This is particularly useful for migrating existing standards documents to the Metanorma format or exporting Metanorma documents to other standard formats.

Usage:
  metanorma convert FILENAME [..options]

Options:
      [--output-format=FORMAT]                # Output format: xml|adoc|iso|niso|ieee
      [--output-file=FILE]                    # Output file path
      [--imagesdir=DIRECTORY]                 # For STS input only: folder with images
      [--input-format=FORMAT]                 # Input format: metanorma|sts|rfc
      [--debug], [--no-debug]                 # Enable debug output
      [--sts-type=TYPE]                       # For STS input only: type of standard to generate
      [--check-type=TYPE]                     # Check against XSD/DTD
      [--xsl-file=FILE]                       # Path to XSL file
      [--split-bibdata], [--no-split-bibdata] # For STS input only: create MN Adoc and Relaton XML
      [--semantic], [--no-semantic]           # For STS input only: generate semantic XML

Converting STS XML to Metanorma

Convert an STS XML file to Metanorma AsciiDoc format:

metanorma convert --input-format sts --output-format adoc \
  --output-file my-document.adoc my-document.xml

When converting from STS, you can specify an images directory and the type of standard:

metanorma convert --input-format sts --output-format adoc \
  --imagesdir images --sts-type iso my-document.xml

To split bibliographic data into separate Metanorma AsciiDoc and Relaton XML files:

metanorma convert --input-format sts --output-format adoc \
  --split-bibdata my-document.xml

Converting Metanorma to STS

Convert Metanorma XML to STS format (ISO, NISO, or IEEE):

metanorma convert --input-format metanorma --output-format iso \
  --output-file my-document.sts.xml my-document.xml

Converting RFC XML

Convert RFC XML to Metanorma AsciiDoc:

metanorma convert --input-format rfc --output-format adoc \
  --output-file my-rfc.adoc my-rfc.xml

Debug mode for conversion

Enable debug output to see detailed information about the conversion process:

metanorma convert --debug --input-format sts --output-format adoc my-document.xml

The --debug option will:

Display the conversion command being executed
Show the output from the conversion process
Print informational messages during conversion
Enable debug mode in the underlying conversion tool

This is particularly useful when troubleshooting conversion issues or understanding how the conversion process works.

List supported doctypes (`metanorma list-doctypes`)

You want to know what are the supported doctypes and what do they support for input and output format? Well, the metanorma list-doctypes can help.

metanorma list-doctypes

To list out the details for a specific flavor run the following command:

metanorma list-doctypes <flavor>

Example 1. Listing document types supported by a processor

metanorma list-doctypes iso

List supported output formats (`metanorma list-extensions`)

Need to know what output formats are supported for a given flavor? We’ve got you covered.

To list out the output formats supported by every single flavor type, run the following command:

metanorma list-extensions

To list out the output formats supported by a particular flavor type, run the following command:

metanorma list-extensions <flavor>

Example 2. Listing extensions supported by a processor

metanorma list-extensions ieee

Export flavor configuration (`metanorma export-config`)

When working with Metanorma tastes, it is necessary to inspect and manipulate the various configuration files that flavors and tastes of Metanorma use to determine flavor behavior.

To do so, run:

metanorma export-config <flavor>

This will export all relevant files from the Metanorma flavor to the directory export-config-<flavor>, preserving the internal directory structure of the Metanorma flavor gem.

If a taste is specified, the taste configuration files are also exported, under the taste/<flavor> subdirectory.

Show processor version (`metanorma version`)

The version command returns the version of the Metanorma processor for a specific flavor.

Example 3. Showing processor version

The version of the ieee processor can be shown with the following command.

metanorma version --type ieee

Show log messages (`metanorma log_messages`)

The log_messages command returns the available log messages for a specific flavor.

Example 4. Showing log messages

The available log messages of the ieee processor can be shown with the following command [added in https://github.com/metanorma/metanorma-cli/releases/tag/v1.14.1]

metanorma log_messages --type ieee

The available log messages are returned listed by category. Many of those log messages are templated, with %s indicating where a value specific to a file location is added.

Bibliography:
	STANDOC_9   : Attachment %s does not exist
	STANDOC_11  : Reference %s is missing a title
	STANDOC_12  : Reference %s is missing a document identifier (docid)
...

Add new template repository (`metanorma template-repo add`)

The template-repo add interface allows you to add your custom template repository to Metanorma, so next time when you need to generate a new document then you can directly use that name to use your custom template from that repository.

metanorma template-repo add my-templates https://github.com/example/my-templates

Generating a Metanorma site

The site subcommand allows you to manage mini site generation using the CLI. This subcommand is more fully documented on site:

metanorma site generate SOURCE_PATH -o OUTPUT_PATH -c metanorma.yml

Using Metanorma behind proxy servers

The metanorma command can read proxy settings from the following environment variables:

HTTP_PROXY for HTTPS and HTTP proxies
SOCKS_PROXY for SOCKS proxies

Please refer to our announcement on proxy support for details.

Note	Since `metanorma` uses Git for templates (and fonts via Fontist, which also relies on Git), Git must also be configured to use proxies. Please refer to this Gist by evantoli for details.

Usage samples

Generate a new Metanorma document using a template (metanorma new)

Generate a new document from an official Metanorma template

Generate a new document from a custom Metanorma template repository

Compile a document (metanorma compile or just metanorma)

Additional compile options

Data URI images (--datauriimage)

Output directory (--output-dir)

Strict mode (--strict)