Metanorma
On this page

Installation Guide

Setting up Metanorma

The Metanorma command-line toolchain can be installed with any of the following installation methods suitable for your platform.

Platform-specific installation

Choose your platform:

Platform-independent installation

The following installation methods are intended for skilled Metanorma experts who develop on Metanorma or require automated actions.

Example

Docker is a platform-independent container engine. The official Metanorma Docker containers on Docker Hub provide a simple and consistent to run Metanorma, especially on continuous integration (CI) environments.

Example

Assuming you know what you're doing, the metanorma-cli gem can be manually installed for development.

You will have to take care of dependencies: an appropriate Ruby version, plus other software depending on the end documents you're building.

Refer to the Development installation guide for details.

Site generation and publishing

Once documents are compiled, the next step is generating a site and publishing it.

  • Site generation -- build a static site from one or more Metanorma documents using metanorma site generate
  • Organization-Scale Publishing Setup -- set up per-document releases, channel-based routing, and portal aggregation for organizations with many document repositories
  • CI/CD integration -- integrate Metanorma into GitHub Actions, GitLab CI, and other CI/CD platforms

Running Metanorma

Refer to the following documentation on how to run the metanorma command:

Installing additional flavors

The method to install additional flavors depends on how Metanorma was installed.

  • If Metanorma was installed through an installation package, such as from SnapCraft (Linux), Homebrew (macOS) or Chocolatey (Windows), these packages install the Metanorma single executable (built from packed-mn). They do not support additional flavors.
  • If Metanorma was installed as a Ruby gem (from GitHub or RubyGems.org), you can add the additional flavor gems to your Ruby installation with one of these methods:
  • Directly install the flavor gem using gem install metanorma-{flavor}
Example

The following command installs the Ribose flavor.

gem install metanorma-ribose
  • Install the flavor gem by specifying it in a Gemfile, then run the bundle command
Example

A Gemfile that adds the Ribose flavor:

source 'https://rubygems.org'
gem 'metanorma-cli'
gem 'metanorma-ribose'
  • If you use Metanorma through Docker, using the official Metanorma Docker images, additional flavors can be installed using Gemfile, and then running the gemfile-to-bundle-add.sh script to add those to the running container.
Example

The Gemfile specified above can be used in the Metanorma Docker images for installing the additional metanorma-ribose flavor with the following command run within the Docker container:

curl -L https://raw.githubusercontent.com/metanorma/metanorma-build-scripts/main/gemfile-to-bundle-add.sh | bash

Installation

Using https://brew.sh/[Homebrew]

brew tap metanorma/metanorma
brew install metanorma

or

brew install metanorma/metanorma/metanorma

Linux

Using https://snapcraft.io[Snap]

The easiest way is to install the Metanorma Snap with a single command:

sudo snap install metanorma

If snapd isn't available on your distribution, use the all-in-one install script described below for various platforms. You will need to have curl installed beforehand.

Tip
For details, please see the metanorma-linux-setup repository.

Install script for Ubuntu

The curl command must be installed.

sudo bash -c "curl -L https://raw.githubusercontent.com/metanorma/metanorma-linux-setup/master/ubuntu.sh | bash"
curl -L https://raw.githubusercontent.com/metanorma/metanorma-linux-setup/master/install-gems.sh | bash

Install script for CentOS

The curl command must be installed.

sudo bash -c "curl -L https://raw.githubusercontent.com/metanorma/metanorma-linux-setup/master/centos.sh | bash"
curl -L https://raw.githubusercontent.com/metanorma/metanorma-linux-setup/master/install-gems.sh | bash

Windows

Using https://chocolatey.org/[Chocolatey]

To install chocolatey follow these instructions

Execute the following in your cmd.exe or PowerShell to install the Metanorma Chocolatey package:

choco install metanorma -y
Tip

For LaTeX processing, a UTF-8 compatible command line interface is necessary. UTF-8 is also presupposed for Metanorma schema validation. If you are using the Windows default command line interpreter cmd.exe, please do run chcp 65001 before using Metanorma. (This may introduce complications of its own, see e.g. Stack Overflow.)

Tip

See the blog post on Metanorma Chocolatey package for more background.

Docker setup

This setup method works for all platforms that support the Docker container framework.

Tip

This method is the recommended way of getting Metanorma installed.

Possible reasons to avoid this method:

  • Performance. Using Metanorma inside Docker container may be a bit slower.
  1. Pull the container:
  2. Specify the :local-cache-only: AsciiDoc attribute in document header to speed up rendering (optional)

To render the document into HTML, Word and XML, execute from within the directory containing the Metanorma document (replacing {my-document-path} with your actual document's filename):

Running the Metanorma container on macOS and Linuxconsole
docker run -v "$(pwd)":/metanorma/ -w /metanorma metanorma/metanorma metanorma compile -t {flavor} -x {output-formats} {my-document-path}
Running the Metanorma container on Windowsconsole
docker run -v "%cd%":/metanorma/ -w /metanorma metanorma/metanorma metanorma compile -t {flavor} -x {output-formats} {my-document-path}
Tip

See metanorma-docker for more information.

Installing gems separately

See Metanorma CLI docs on how to install the Ruby gem on its own.

Use-cases

Follow the links for your level of expertise with Metanorma:

New User

If you are fairly new, follow these steps to get acquainted with our tool.

Experienced Users

If you have already used Metanorma, then probably you'd like to directly navigate to the Authoring Guide. Follow these steps.

Expert

If you are well-versed with the tool, probably you belong to the developer level. Follow these steps to navigate to Developer Docs.