Setting up Metanorma

To build documents with Metanorma, you need to have the Metanorma command-line toolchain installed.

The toolchain consists of metanorma-cli Ruby gem and its dependencies.

In general, these installation methods are recommended.

Platform-specific methods:

macOS: via our Homebrew formula
Linux: via our Snapcraft package
Windows: via our Chocolatey package

Platform-independent methods:

Docker: the Metanorma Docker container
Ruby: install the native Ruby metanorma-cli gem

Tip	Full manual Assuming you know what you’re doing, you can manually install the `metanorma-cli` gem. 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 Metanorma CLI installation docs for details.

macOS

Using Homebrew

brew tap metanorma/metanorma
brew install metanorma

brew install metanorma/metanorma/metanorma

Linux

Using 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 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. If you are using the Windows default command line interpreter `cmd.exe`, please do run `chcp 65001` before using Metanorma.

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.

Pull the container:
```
docker pull metanorma/metanorma
```
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 Linux

docker run -v "$(pwd)":/metanorma/ -w /metanorma metanorma/metanorma metanorma compile -t {flavor} -x {output-formats} {my-document-path}

Running the Metanorma container on Windows

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.