Install and Run Antora Quickstart :: Antora Docs

Install and Run Antora Quickstart :: Antora Docs
Antora
3.1
Antora
3.1
3.0
Antora Assembler
1.0.0-beta.20
Antora Collector Extension
1.0
Antora Default UI
Antora Maven Plugin
1.0.0-alpha.5
Gradle Antora Plugin
1.0
3.1
3.0
Edit this Page
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.
You can skip the installation steps by using the
Docker image
provided by the Antora project.
Instead of having to worry about installing Node.js and Antora, all you need is Docker or Podman to run Antora in a container.
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.20.2
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.
Install nvm and Node.js on Linux
Install nvm and Node.js on macOS
Install nvm and Node.js on Windows
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.20.2
$ nvm alias default 16.20.2
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 initialize a
package.json
file and 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
Refer to
Security Bulletins
to remediate any security vulnerabilities that are reported.
Verify the
antora
command is 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.1.14
@antora/site-generator: 3.1.14
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
$ npm i -g antora
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 with remote sources
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.
antora-playbook.yml
site:
title: Docs Site
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
A page from a component version to be used as the home page for your site.
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.
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 antora-playbook.yml
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.
$ npx antora --fetch antora-playbook.yml
You can turn on the fetch behavior permanently by setting the
fetch key
in your playbook.
For more detailed information about running Antora and troubleshooting help, see
Run Antora to generate your site
Create a playbook with a local source
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.
$ git init
git commit --allow-empty -m init
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.
$ mkdir -p modules/ROOT/pages
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.
modules/ROOT/pages/index.adoc
= Welcome!

You are home.
Create one additional page so that you can study how the navigation is put together.
modules/ROOT/pages/new-page.adoc
= New Page

You've found a new page.
Next, create a navigation file so that each page contains links to navigate to the other pages.
modules/ROOT/nav.adoc
* xref:new-page.adoc[]
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
antora.yml
name: project-name
version: ~
title: Project Name
nav:
- modules/ROOT/nav.adoc
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.
antora-playbook.yml
site:
title: Docs Site
start_page: project-name::index.adoc
content:
sources:
- url: .
branches: HEAD
ui:
bundle:
url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
snapshot: true
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.
📒 docs-site
📂 modules
📂 ROOT
📂 pages
📄 index.adoc
📄 new-page.adoc
📄 nav.adoc
📄 antora.yml
📄 antora-playbook.yml
You can now generate the site as you did before.
$ npx antora antora-playbook.yml
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:
.gitignore
/build/
/node_modules/
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 earlier in this quickstart to become familiar with how it works.
Learn how to
organize your content files
for Antora.