Install Antora

Assumptions:

  • You’ve installed the base build tools on your Linux or macOS machine (not applicable for Windows).

  • You’ve installed Node 8 on your Linux, Windows, or macOS machine.

On this page, you’ll learn:

  • How to install the Antora CLI.

  • How to install the default Antora site generator.

To generate documentation sites with Antora, you need the Antora command line interface (CLI) and an Antora site generator pipeline. Once these packages are installed, you can use the antora command to publish a site.

Install the Antora CLI

We’ll begin by installing the Antora CLI using npm, the package manager for Node. This package manager was installed when you installed Node.

Open a terminal and type:

$ npm i -g @antora/cli
The @ at the beginning of the package name is important. It tells npm that the cli package is located in the antora group. If you omit this character, npm will assume the package name is the name of a git repository on GitHub.

We recommend installing (i subcommand) the CLI package globally (-g flag) so the antora command, which is provided by the CLI package, becomes available on your PATH.

When we say “globally” here, it does not imply system-wide. It means the location where Node is installed. If you used nvm to install Node, this location will be inside your home directory (thus not requiring elevated permissions).

If you prefer Yarn over npm, use this command instead:

$ yarn global add @antora/cli
If you’re using a system-wide Node installation managed by a package manager, you may run into permission problems when installing packages. In that case, just drop the -g flag so that the package is installed under the node_modules folder in the current directory.

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

$ antora -v

If you installed the package locally, meaning without the -g flag, you’ll need to prefix the command as follows:

$ $(npm bin)/antora

If installation was successful, the command should report the version of Antora.

$ antora -v
1.1.x

Install the default Antora site generator

Next, install the default site generator.

To install the generator globally, type:

$ npm i -g @antora/site-generator-default
The @ at the beginning of the package name is important. It tells npm that the cli package is located in the antora group. If you omit this character, npm will assume the package name is the name of a git repository on GitHub.

If you prefer Yarn over npm, use this command instead:

$ yarn global add @antora/site-generator-default

If you don’t want to install the generator globally (or run into permission problems trying), you can opt to install it inside the playbook project (the project that contains the playbook file(s) for your site).

Switch to the playbook project and type:

$ npm i @antora/site-generator-default
If you’re on Linux and get an error message about libcurl-gnutls.so.4, you’ll need to patch or recompile nodegit.

What’s next?

Now that the Antora CLI and default site generator are installed, you are ready to: