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.
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:
$ nvm install --lts $ nvm alias default 12
$ nvm install 12.16.2 $ nvm alias default 12.16.2
Once you’ve installed Node, it’s time to 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
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.
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.|
|See the Antora playbook for more detailed information about the playbook file.|
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
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 how to organize your content files for Antora.