Install and Run Antora Quickstart

This quickstart walks you through the initial steps required to install Antora and generate your first documentation site.

On this page, you’ll learn:

  • How to install Node.js.

  • How to install Antora.

  • How to create your first Antora playbook.

  • How to run Antora to generate a site based on the playbook.

Install Node.js

Antora requires an active long term support (LTS) release of Node.js. To see if you have Node.js installed, and which version, open a terminal and type:

$ node -v

This command should return an active Node.js LTS version number, for example:

$ node --version
v16.16.0

If you have an active Node.js LTS version on your machine, you’re ready to install Antora.

If no version number is displayed in your terminal, you need to install Node.js. We recommend using nvm to install Node.js, though you are free to take a different path. Follow one of these guides to learn how to install nvm and Node.js on your platform.

If you have Node.js installed, but it isn’t an active LTS version, you need to upgrade Node.js. To upgrade to the latest Node.js LTS version and set it as your default version, type the following commands in your terminal:

Linux and macOS
$ nvm install --lts
$ nvm alias default 16
Windows
$ nvm install 16.16.0
$ nvm alias default 16.16.0

Once you’ve installed Node.js, it’s time to install Antora.

Install Antora

To generate documentation sites with Antora, you need the Antora command line interface (CLI) and the Antora site generator. To install Antora, begin by making a new directory for your site named docs-site and switch to it.

$ mkdir docs-site && cd docs-site

Next, let’s install the required packages 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.0 @antora/site-generator@3.0

Verify the antora command is now available by running:

$ npx antora -v

If the installation is successful, the command will report the version of the Antora CLI and site generator packages you specified.

$ npx antora -v
@antora/cli: 3.0.3
@antora/site-generator: 3.0.3

These versions can also be found in package.json, which you can use to upgrade Antora.

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

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

You can verify that the antora command is available on your path by running:

$ antora -v

We strongly recommend that you install Antora within the playbook project. This strategy makes it easier to manage the version of Antora. It also ensures that the version of Antora matches the version for which the playbook was made.

Now you’re ready to create your first playbook.

See Install Antora for more detailed information and additional installation methods.

Create a playbook

To produce a documentation site, Antora needs a playbook. Using your preferred text editor or IDE, create a new file and populate it with the configuration information listed below. Save this file as antora-playbook.yml in the docs-site directory you made in the previous step. This playbook file will create a site using the Antora demo repositories.

antora-playbook.yml
site:
  title: Antora Docs
  start_page: component-b::index.adoc (1)
content:
  sources: (2)
  - url: https://gitlab.com/antora/demo/demo-component-a.git
    branches: HEAD
  - url: https://gitlab.com/antora/demo/demo-component-b.git
    branches: [v2.0, v1.0]
    start_path: docs
ui: (3)
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true
1 A page from a component version to be used as the home page for your site.
2 The sources category contains the list of git repository locations, branch name patterns, and other repository properties that Antora uses when aggregating the site content.
3 The ui category contains keys that specify the location of the UI bundle and how it should be processed.
See the Antora playbook for more detailed information about the playbook file.

Run Antora

To generate the site, point the antora command at your playbook file. In the terminal, make sure you’re in docs-site directory, then type:

$ npx antora --fetch antora-playbook.yml

Antora will clone the content and UI repositories and generate your documentation site to the default output directory.

By default, Antora does not sync the repository once it clones it. Instead, it tries to work offline by using the repository in the cache it previously cloned. This default can create some confusion when getting started. Therefore, we recommend including the --fetch option in the command until you’re more familiar with Antora. You can also set the fetch key in your playbook to enable this setting permanently.

Navigate to the docs-site/build/site directory and open the index.html file in your browser to see the result. Congratulations! You’ve successfully built your first site with Antora.

For more detailed information about running Antora and troubleshooting help, see Run Antora to generate your site.

Learn more