Metanorma: Aequitate Verum

Generate document sites with the Metanorma CLI

Author’s picture Abu Nashir on 19 Dec 2020

A set of Metanorma documents can be compiled and published as a document site.

It is not uncommon that multiple Metanorma documents are managed within a single repository. These cases include:

  • multiple documents belong to the same series;

  • a single document published to multiple venues;

  • multiple parts of a document collection.

The NIST Automated Cryptography Validation Protocol (ACVP) series is one such example.

In fact, the Metanorma sample document sites for every flavor provides multiple sample documents arranged under a single site.

Previous to this announcement, there are a couple tools (and hoops) to jump through to make this happen:

  1. Use a build dependency tool such as make (our favorite) to manage shared dependencies

  2. Use a static-site generator (SSG), such as Relaton or Jekyll to make the generated documents available in an HTML index.

  3. Link these tools up with Metanorma and generate the document renders, the publishable site, and finally deploy the site.

Cumbersome to say the least!

Many Metanorma users have been using the “unofficial” Makefile that is being used in Metanorma sample document sites. It typically works fine, except that over time it grew and became hard to maintain.

I’m happy to announce that site generation functionality is now available as part of the official CLI.

Let’s go through a quick demo to see it in action, and then try customizing the build.

Demo setup

Let’s use the Metanorma ITU sample repo as an example.

There are several files there, but to keep the demo short, we focus on the following files and directories.

mn-samples-itu              # Root directory
|
|-- sources                 # Source directory
|   |-- images              # Nested images for assets
|   |-- G.191.adoc          # Individual document inside sources
|   |-- G.650.1-201803.adoc # Another individual document
|   |-- ...
|
|-- metanorma.yml           # Configuration file in root directory
|...

There are two important components that relate to site generation:

  1. the metanorma.yml configuration file;

  2. the individual documents under the sources/ directory

Under sources there are two Metanorma AsciiDoc files (the “source documents”) and an images folder for assets.

Generate the site

To generate the site, all you need is to install the latest version of the Metanorma CLI.

Then run the following:

metanorma site generate ./sources

The ./sources path indicates to Metanorma that the documents inside this path should be compiled and built into a site.

Specifically, this is what Metanorma does:

  • scan through ./sources and discover any Metanorma document files;

  • compile those documents;

  • create site/ and place within an index.html and the compiled document files, linked from the index.

Voila! You will have the site/ created with HTML ready to deploy (or package!).

During the process, Metanorma will also print out the details in the terminal to keep you updated.

This command is the very bare minimum to generate a site, but let’s look at the help command to see what’s available.

Running metanorma site help generate shows the basics of the command:

$ metanorma site help generate

Usage:
  metanorma site generate SOURCE_PATH

Options:
  -c, [--config=CONFIG]          # The metanorma configuration file
  -o, [--output-dir=OUTPUT_DIR]  # Output directory for the generated site
                                 # Default: /home/[your-repo-path]/site

This covers most use cases, but what if we only want to include specific files or add custom site metadata? The next section is for you.

Specify output path

You can also specify the output path of the generated site. By default, metanorma site generate places the generated site under the directory site/ (auto-created if it doesn’t exist) relative to the current working directory.

To specify the output path, you can use the --output-dir={path} (-o {path}) option.

This command generates the site at production/.

metanorma site generate ./sources -o production

Customize site generation

You might have noticed the --config={file} (or just -c {file}) option in the site generate help documentation. There is indeed an option to customize the site build.

This option takes a YAML file and uses that as site generation instructions,

Currently it offers the following customizations:

  • Build a site with specific source files

  • Customize site metadata (e.g., site title, site copyright)

Build with specific source files

By default, metanorma site generate generates documents for the entire folder. But let’s say we only want to generate the site with a single file: sources/G.191.adoc.

Here’s how we do it through the Metanorma site configuration file: (please pay attention to the node structure)

# filename: metanorma.yml

metanorma:
  source:
    files:
      - G.191.adoc

The Metanorma site configuration file uses the following structure:

  • at the top level we have the key metanorma followed by the key source below

  • under the key source, there is one more level of nesting with files

Under files, relative paths to documents (each entry is a path to a document; relative to the directory of the config file) can be provided as an array (each YAML array value is prefixed with a hyphen-space - xxx.adoc).

If you need to more flexibility, the wildcard “asterisk” (*) is also supported for file paths.

By default, Metanorma will look for a config file named metanorma.yml in the current directory.

This follow command will build the site with the file paths you specified in metanorma.yml.

metanorma site generate ./sources -o site-folder

In the case where you juggle multiple site configurations, or wish to name your configuration file differently, you can specify a different path for the configuration file, such as:

metanorma site generate ./sources --config production.yml

The site generation functionality also allows the provision of a custom title for the hero area or the name for the documents that form site, which is useful to indicate ownership or copyright.

To do that we can use the same configuration file and add the following information.

# filename: metanorma.yml

metanorma:
  source:
    files:
      - G.191.adoc
      - ...
  collection:
    name: ITU-T G.191 and related documents
    organization: International Telecommunication Union

Under the collection key, you can specify:

  • name, the site title;

  • organization, the owner of the site.

A complete configuration file is shown here for reference: Sample Metanorma Config

Final thoughts

Thanks for making it this far — we’ve tried to build these commands in a way that match our users' feedback (as well as how we wished to use internally).

While this post discusses several customization options, if you would like to see more or have any feedback — please file an issue at our CLI GitHub repo!

Reference