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.

Docker

Tip	Installing via Docker 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.

Ruby gem

Tip

Manual installation

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

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.

Continuous delivery environments

Metanorma is often run on continuous integration (CI) and continuous deployment (CD) environments.

GitHub Actions and GitLab CI/CD

Running Metanorma

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

Metanorma manual for more details on its command options; and
Using Metanorma for instructions on how to use Metanorma.

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}
  Tip
  
  Installing a flavor through the gem install command
  
  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
  Tip
  
  Installing a flavor through a Gemfile
  
  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.

Tip

Installing a flavor to a Metanorma Docker container

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