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 documentation component repositories or Antora’s Demo docs components.
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.
Where files are cached.
How to update the cache.
How to preview a generated site locally.

Antora demo playbook and components

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

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 documentation components.

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

Cache

When Antora runs the first time, it will save resources it fetches over the network in a local cache. Antora caches two types of resources:

cloned git repositories
downloaded UI bundles

Antora stores these resources in the cache directory, which are further organized under the content and ui folders, respectively. The default cache directory varies by operating system. You can override the default cache location—listed here in order of precedence—using:

the --cache-dir CLI option,
the ANTORA_CACHE_DIR environment variable, or
the runtime.cache_dir key in the playbook.

If you want Antora to update the cache on subsequent runs, pass the --fetch option to the Antora CLI or set the runtime.fetch key to true in the playbook. This switch will force Antora to run a fetch operation on each repository it previously cloned. It will also force Antora to download a fresh copy of the UI bundle, if the URL is remote.

If you want to clear the cache altogether, locate the Antora cache directory on your system and delete it.

Private git repositories

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

Local site preview

Since Antora generates static sites, you do not have to publish the site to a web server to view it. A site generated by Antora works just as well using the browser’s local file: protocol. This characteristic of an Antora site is an essential tool for previewing your work.

To view the site locally, navigate to any HTML page inside the destination folder in your browser. If you’re following along with the Demo, look for the file build/site/index.html in your project. You will be viewing the HTML pages through the file: protocol of the browser, which you can see in the location bar.

Run a local server (optional)

Although the site is viewable without a web server, you may still need to view your site through a web server to test certain features, such as indexified URLs, caching, or scripts that don’t work over the file: protocol). You can use the node-srv package for this purpose. node-srv is a simple, static web server for Node.

Install the node-srv package globally using npm:

demo-site $ npm i -g node-srv

or Yarn:

demo-site $ yarn global add node-srv

That puts a command by the same name on your PATH.

Now launch the web server by pointing it at the location of the generated site. In the terminal, type the command name, node-srv, followed by the -r flag, then the location of the generated site (i.e., the output dir). After launching the command, the local address of the web server will be displayed in your terminal.

demo-site $ node-srv build/site

You should see the following output in your terminal:

Server node-srv running at
 => http://localhost:8000

Logs are off.

Paste the provided URL into the location bar of your browser to view your site through a local web server.

Press Ctrl+C to stop the server.

If you get a port conflict when starting the server (i.e., listen EADDRINUSE: address already in use), you can use the -p <port> option to change to another port. For example, use -p 5000 to switch to port 5000.

Publish to GitHub Pages

Antora is designed to create sites that run anywhere, whether it be on a static web host or the local filesystem. However, some hosts offer “features” that mess with Antora’s output. GitHub Pages is one of those hosts.

By default, GitHub Pages runs all files through another static site generator named Jekyll (even if they aren’t using a Jekyll project structure). Since Antora already produces a ready-made site, there’s absolutely no need for this step. This processing is particularly problematic since Jekyll has the nasty side effect of removing all files that begin with an underscore (_). Antora puts UI files in a directory named _, and places images under the directory name _images, which Jekyll subsequently erases. As a result, no UI, no images.

Fortunately, there’s a way to disable this “feature” of GitHub Pages. The solution is to add a .nojekyll file to the root folder of the published site (i.e., the output directory).

One way to add this file is to touch the .nojekyll file in the output directory after Antora runs, but before committing the files to GitHub Pages. For example:

$ touch build/site/.nojekyll

To avoid the need for the extra command, the other way to do it is to inject the file using Antora’s supplemental UI feature. To do so, add the following supplemental_files block under the ui category in your playbook file:

ui:
  bundle:
    url: <url-of-bundle-goes-here>
  supplemental_files:
  - path: .nojekyll
  - path: ui.yml
    contents: "static_files: [ .nojekyll ]"

The presence of the .nojekyll file at the root of the gh-pages branch tells GitHub Pages not to run the published files through Jekyll. The result is that your Antora-made site will work as expected.