Install Antora

To generate and publish documentation sites with Antora, you need the Antora command line interface (CLI) and the official Antora site generator or a custom one. This page explains how to install Antora using its default configuration.

Assumptions:

You’ve installed an active Node.js LTS release on your Linux, Windows, or macOS machine.

On this page, you’ll learn:

How to run Antora without installing it.
How to install Antora locally (recommended).
How to install the Antora CLI and site generator packages globally.

Try before you install

If you’re just evaluating Antora, you can use npx to run it without having to install it first.

$ npx antora -v

The npx command, provided by Node.js, can run a command directly from a local or remote npm package. If any required packages are not present in the local project dependencies, npx will install them into a cache folder (typically $HOME/.npm/_npx) before running the command. If the name of the command matches the name of the package that provides it, you don’t have to specify the package name. In this case, the antora package, which bundles the CLI and site generator, provides the antora command and the dependencies it needs to run.

Using npx without installing any packages is only intended for evaluation, and only works when using Antora by itself. Once you need additional packages, you’ll need to install them along with Antora before running npx.

You’ll see later that we recommend using the npx command to run Antora whenever you have installed it locally.

Locally vs globally

When we say “locally” on this page, we mean within the playbook project (i.e., the directory where the playbook file for the site is located) or any parent folder. We recommend installing Antora locally, especially if you’re managing several documentation sites. Installing Antora locally makes it easier to manage the version of Antora and ensures that the version of Antora matches the version for which the playbook was made. It also avoids any permission problems you may run into when trying to install Antora globally.

When we say “globally” on this page, it doesn’t necessarily imply system-wide. Rather, it means the location where Node.js is installed. If you used nvm to install Node.js, this location will be inside your home directory (thus not requiring elevated permissions). We only recommend installing Antora globally if you’re familiar with how Antora works and are comfortable with this setup.

Your best chance for success is to install Antora locally. At the very least, you should start there.

Install Antora locally

To install Antora locally, begin by switching to the directory of your playbook project (creating it, if necessary). We’ll assume here that the name of this folder is docs-site.

$ cd docs-site

Next, let’s install the CLI package within the playbook project so you can run the antora command using npx.

$ node -e "fs.writeFileSync('package.json', '{}')"
$ npm i -D -E @antora/cli@3.1

As an alternative to the first command, you can use npm init -y. However, npm init adds a lot of extra keys that you may not need.

The @antora/cli package and its dependencies will be installed into the node_modules folder inside your playbook project. The optional -D option tells npm to save the package as a development dependency in package.json. The -E option tells npm to store the exact version in package.json rather than prefixing it with a semver range operator.

The @ at the beginning of the package name informs npm that the cli package is located under the @antora scope. If you omit this character, npm will assume the package name is the name of a git repository on GitHub.

The second @ in the package name designates the start of the requested version number. Except for prerelease versions, you can specify the major and minor segments only (e.g., @3.1), which ensures you retrieve the latest patch release.

When you install Antora locally, the antora command is not placed on your PATH. Instead, you run the antora command using npx (i.e., npx antora).

Verify the antora command is available through npx by running npx antora -v.

$ npx antora -v

This command should report the version of the Antora CLI in the terminal.

@antora/cli: 3.1.9
@antora/site-generator: not installed

The npx command will look for the antora command installed within the playbook project or any parent directory of the playbook project. If you’re prompted to install the antora package, then the CLI was not found.

If you’re using Bash, you can save some typing by creating an alias for npx antora named antora:

$ alias antora='npx antora'

Now you can run antora without having to remember to prefix it with npx:

$ antora -v

You can bypass this alias by prefixing the command with a backslash, which will search for antora on your PATH instead.

$ \antora -v

Although npx finds the antora command and reports the CLI version, we’re still missing the site generator. Next, install the site generator package within the playbook project:

$ npm i -D -E @antora/site-generator@3.1

The @antora/site-generator package and its dependencies will be installed into the node_modules folder inside your playbook project. Antora’s CLI will look for the site generator package in this folder first before looking in the global installation folder.

Now when you run npx antora -v, you should see the version of both the Antora CLI and the site generator printed in the terminal.

@antora/cli: 3.1.9
@antora/site-generator: 3.1.9

If you open package.json, you’ll see the version of these packages listed there too, as development dependencies.

{
  "devDependencies": {
    "@antora/cli": "3.1.9",
    "@antora/site-generator": "3.1.9"
  }
}

You’ll also notice an additional file named package-lock.json. This file stores the resolved version of all packages and their dependencies. You may choose to commit this file when you commit package.json.

If you’re reinstalling Antora, it’s best to first remove the node_modules folder. If you also want to get the latest version of each dependency, remove the package-lock.json file as well. If you remove the node_modules folder, be sure to install the CLI package again. Another option is to use npm ci, which will automatically remove node_modules when reinstalling.

If the antora command reports the version of both the CLI and the site generator, and those versions match, that confirms you have installed Antora correctly.

Install Antora globally

You have the option of installing Antora globally so that the antora command is available on your PATH. To install Antora globally, pass the -g option to npm i.

$ npm i -g @antora/cli@3.1 @antora/site-generator@3.1

Verify the antora command is available on your PATH by running:

$ antora -v

If installation was successful, the command should report the version of the Antora CLI and site generator.

$ antora -v
@antora/cli: 3.1.9
@antora/site-generator: 3.1.9

The benefit of installing Antora globally is that it is always available in your terminal, no matter what directory you are in. While this may seem convenient at first, there are problems with this strategy. The version of Antora you have installed may not match the version of Antora for which the documentation site was made. And there’s no way for Antora or the documentation site to verify these are the same. So you may end up running into esoteric problems and find yourself struggling to get them in sync. Installing Antora locally and running it using npx will give you the best chance for success and compatibility.

If you’re using a system-wide Node.js installation managed by your operating system’s package manager, you may run into permission problems when installing packages globally. In that case, you’ll need to install Antora directly in your project repository.

Learn more

Now that Antora is installed, you’re ready to:

Set up your own playbook or use the Demo playbook.
Organize your content source files and repositories or use Antora’s Demo content repositories.
Run Antora and generate a documentation site.