Run Antora to Generate Your Site

Assumptions:

You’ve installed the Antora CLI and a site generator pipeline.
You have your own playbook, or you’re using the Demo playbook.
Your playbook is configured to access at least one of your own repositories containing content source files or Antora’s Demo content repositories.
Your playbook is configured to use a custom UI bundle or Antora’s default UI bundle.

On this page, you’ll learn:

How to run Antora and generate a site.

Antora demo playbook and content repositories

You don’t need to set up a playbook file, component version, or UI to evaluate Antora. Instead, you can use the Antora demo playbook and content repositories.

The demo consists of a playbook repository containing a playbook file and content repositories (component-a and component-b) to which that playbook refers. It also uses the UI bundle produced by the default UI project.

Once you’ve installed Antora, you can run Antora using the demo materials to explore its capabilities. The instructions and examples on this page will guide you through the process.

Choose a playbook

To produce a documentation site, Antora needs a playbook. But first, you’ll need to create or choose a directory where you’ll store the playbook and where the generated site files will be saved (assuming you use the default output configuration).

For the examples on this page, we’ll use the demo playbook and content repositories.

Open a terminal and make a new directory named demo-site.
```
~ $ mkdir demo-site
```
Switch (cd) into the directory you just made.
```
~ $ cd demo-site
```

Using your preferred text editor or IDE, create a new playbook file named antora-playbook.yml and populate it with the contents of the following example. Or, you can download the playbook file from the demo project repository.

antora-playbook.yml

site:
  title: Antora Demo Site
  url: https://my-antora-demo-site.org (1)
  start_page: component-b::index.adoc (2)
content:
  sources:
  - 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:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true

1	The 404 page and sitemap files are only generated if the site `url` key is set. The sitemap files are only generated if the value of the site `url` key is an absolute URL.
2	The site `start_page` key accepts the same resource ID syntax that’s used in xrefs.

Save the playbook as antora-playbook.yml in the demo-site directory you made in Step 1.

Run Antora

To generate the site with the default Antora site generator, point the antora command at your playbook file. In the terminal, type:
demo-site $ antora antora-playbook.yml
If Antora is installed locally, you’ll need to prefix the Antora command with npx:
demo-site $ npx antora antora-playbook.yml
Antora will clone the content repositories. The cloning progress of each repository is displayed in the terminal.
Repository cloning progress
[clone] https://gitlab.com/antora/demo/demo-component-a.git [################] [clone] https://gitlab.com/antora/demo/demo-component-b.git [################]
Once cloning is complete, Antora converts the AsciiDoc pages to embeddable HTML, wraps the HTML in the UI page templates, then assembles the pages into a site under the destination folder, which defaults to build/site.

Antora has completed generation when the command prompt ($) reappears in the terminal. If the terminal is interactive (TTY), Antora will also print a message that the site generation is complete. The message will include the URL where you can view the site locally. (You can override Antora’s TTY detection by setting the IS_TTY environment variable to true or false).

If something goes wrong during generation, you’ll see an error message in the terminal.

error: a message that summarizes what went wrong

If this message does not provide enough information to fix the problem, you can ask Antora for more context. To tell Antora to reveal the calls leading up to the error (i.e., the stacktrace), run the antora command again, this time with the --stacktrace option:

demo-site $ antora --stacktrace antora-playbook.yml

Share this stacktrace when asking for help.

Switch into the site folder (cd) and list (ls) its contents.

demo-site $ cd build/site/

Inside the build/site folder, run:

site $ ls -1

You should see the following list of files and directories:

_
404.html
component-a
component-b
index.html
sitemap-component-a.xml
sitemap-component-b.xml
sitemap.xml

The 404 page and sitemap files will be missing if the site.url property is not defined in your playbook. The main sitemap file is actually a sitemap index. That file links to the sitemap for each component, which is where the URL for the individual pages can be found.

This list includes the entry point of your documentation site, index.html.

On some operating systems, you can open the site directly from the command line by typing open, followed by the name of the HTML file.
site $ open index.html
Or, you can navigate to an HTML page inside the destination folder in your browser. If you’ve been following along with the Demo materials, once you find the demo-site directory, navigate to the file build/site/index.html.

Private git repositories

Antora can authenticate with private repositories using HTTP Basic authentication over HTTPS. See Private repository authentication to learn more.

Repositories with large pack files

Antora may fail to read a git repository if it contains very large pack files (those > 2g). If this situation occurs, you will get the following error:

FATAL (antora) : Cannot read properties of null (reading 'slice')

This failure is caused by a known limitation of the git client Antora uses (isomorphic-git). The limitation is due to a hard limit in the memory settings of the Node.js runtime. Here’s the underlying error message:

RangeError [ERR_FS_FILE_TOO_LARGE]: File size is greater than 2 GiB

2g is the max buffer size in Node.js. In other words, Node.js has an upper limit to the size of a file it’s able to read into memory. If the pack file exceeds this size, Node.js and, in turn, isomoprhic-git, will fail. In order to read larger files, isomorphic-git would have to switch to streams instead of putting the whole file in a buffer, if that’s even feasible.

For a local git repository, the workaround is to configure git so it caps the size of any pack files it creates locally. This is done using the pack.packSizeLimit config setting.

$ git config pack.packSizeLimit 1g && git gc

You can find information about this setting on the git-pack-objects help page in the git documentation.

Keep in mind that this workaround will only help with a local repository (a repository that is already cloned and configured). Changing the pack size of the local repository isn’t going to change the storage settings of the remote repository. The pack.packSizeLimit needs to be adjusted on the git server as well so git doesn’t attempt to send pack files that are too large over the wire.