Install and Run Antora Quickstart

This quickstart walks you through the general steps required to install Antora and generate a basic documentation site.

On this page, you’ll learn:

  • How to install Node.js.

  • How to install the Antora.

  • How to create your first Antora playbook.

  • How to run Antora and generate a site using a playbook.

Install Node.js

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

$ node --version

This command should return an active Node LTS version number.

$ node --version
v12.16.2

If you have an active Node 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.

If you have Node installed, but it isn’t an active LTS version, you need to upgrade Node. To upgrade to the latest Node 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 12
Windows
$ nvm install 12.16.2
$ nvm alias default 12.16.2

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

Install Antora

Before installing Antora, make a new directory for your site named docs-site and switch to it.

$ mkdir docs-site
$ cd docs-site

To generate documentation sites with Antora, you need the Antora CLI and the Antora site generator. Let’s install these packages globally to make them available on your PATH:

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

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

$ antora -v

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

$ antora -v
2.3.x

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: master
  - 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/master/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:

$ 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