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.

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 more.

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.
Building PDF deliverables. Due to a pending bug (see metanorma-docker#42), building in PDF doesn’t currently work with Metanorma in Docker.

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.

macOS

Using Homebrew

brew tap metanorma/metanorma
brew install metanorma

This uses Metanorma’s Homebrew formula.

To install using the HEAD development version of the formula, run:

brew install --HEAD https://raw.githubusercontent.com/metanorma/homebrew-metanorma/master/metanorma.rb

All-in-one script

Run the following for an automatic install that would prepare a fresh system to work with Metanorma.

Note	This installs not just the Metanorma components, but also prerequisites such as Homebrew and basic tools like Sublime Text.

This should take less than 15 minutes depending on your machine and Internet connection:

bash <(curl -s https://raw.githubusercontent.com/metanorma/metanorma-macos-setup/master/metanorma-setup)

Linux

Linux setup uses all-in-one script. You need to have curl installed beforehand.

Tip	See more in metanorma-linux-setup repository.

Ubuntu

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

CentOS

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

Execute the following:

Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))
refreshenv
cinst msys2 --params "/NoUpdate" -y # install msys2 without system update
cinst metanorma -y
refreshenv

Tip	Windows encoding in cmd.exe usually not UTF-8, so to make it UTF-8 please run `chcp 65001`. This workaround critical when you need work with LaTeXML

Tip	See also the blog post on Metanorma Chocolatey package.

Docker installation shortcut

Run this command in your cmd.exe or PowerShell to install the Metanorma Docker container and all prerequisites (see Docker setup):

bitsadmin /transfer get https://raw.githubusercontent.com/metanorma/metanorma-windows-setup/master/install.bat %cd%\install.bat & .\install.bat

Installing gems separately

See Metanorma CLI docs on how to install that gem on its own, be sure to note the dependencies.