Install and Run Antora Quickstart

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:

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

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:

Once you’ve installed Node.js, it’s time to 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.

Next, let’s initialize a package.json file and install the required packages within the playbook project so you can run the antora command using npx.

Verify the antora command is available by running:

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

These versions can also be found in package.json (pulled in transitively by the antora package), 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.

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

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.

To produce a documentation site, Antora needs a playbook, which is defined using a playbook file. The simplest way to start using Antora is to point the playbook at existing documentation stored in remote repositories (i.e., content sources). For this example, we’ll use the content sources from the Antora demo repositories.

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.

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 will clone the content and UI repositories and generate your documentation site into the default output directory and report the file URL to that directory in the terminal.

To see the result, navigate to the provided URL in your browser, which renders the index.html file located in the docs-site/build/site directory. Congratulations! You’ve successfully built your first site with Antora.

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 turn on the fetch behavior permanently by setting the fetch key in your playbook.

Antora also supports local content sources, which are git repositories that have been cloned or otherwise initialized on the current machine. What that means is that it’s possible to create a site from a local repository that contains both the playbook and the content source(s) (i.e., a mono site). For this example, you can set up everything locally in the docs-site directory created earlier without having to rely on any remote git repositories.

To start, it’s necessary to initialize the docs-site as a local git repository.

If you’re adding Antora to an existing local git repository, this step is not required.

Next, create enough of the standard directory hierarchy to store a couple of pages, the navigation file, and the component version descriptor for your content source root. This content source root could be placed at a start path such as docs, but we’ll use the root of the repository for now.

Using your preferred text editor or IDE, create a the start page for the component version and populate it with a page title and some text.

Create one additional page so that you can study how the navigation is put together.

Next, create a navigation file so that each page contains links to navigate to the other pages.

Notice that the start page for the component version is not included. That’s because it’s automatically added as the root of the navigation tree.

To finish putting together the content source root, create the component version descriptor, antora.yml. This file identifies a content source root and, in turn, defines a component version. We’ll create a versionless component named project-name, though you make this a versioned component or even the ROOT component.

Now that you have a local content source defined, you can create a playbook that uses it. Save the playbook file as antora-playbook.yml adjacent to antora.yml at the root of the docs-site directory.

This repository defines the start page for the component version we created as the start page for the site. The start_page playbook key (under the site key) isn’t required if the component version you created is the ROOT component.

Here’s how the file and directory structure inside the docs-site directory should look when you’re done.

You can now generate the site as you did before.

Antora will generate your documentation site to the default output directory and report the file URL to that directory in the terminal. To see the result, navigate to the provided URL in your browser, which renders the index.html file located in the docs-site/build/site directory.

To instruct git to ignore the output directory and any locally installed npm packages, create a .gitignore file and populate it with the following contents:

To learn more about local content sources, refer to Use local content repositories. Local content sources can be mixed with remote content sources in the same playbook, so try adding the remote content sources shown ealier in this quickstart to become familiar with how it works.