Run Antora to Generate Your Site
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.
You don’t need to set up a docs component or create a UI to try out Antora. We’ve set up a playbook file, several content source repositories, and provided a default UI bundle. As soon as you’ve installed Antora, you can run Antora with the Demo materials and explore its capabilities. The instructions and examples on this page will show you how to operate Antora with the Demo materials.
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 materials.
Open a terminal and make a new directory named demo-site.
~ $ mkdir demo-site
cd) into the directory you just made.
~ $ cd demo-site
Using your preferred text editor or IDE, create a new playbook file named site.yml and populate it with the contents of the following example. You can also download a sample playbook file from the Demo repository.site.yml
site: title: Antora Demo Site url: https://example.org/docs (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 property is set. 2 The site.start_page property accepts the same page ID syntax that’s used in xrefs.
Save the playbook as site.yml in the demo-site directory you made in Step 1.
To generate the site with the default Antora site generator, point the
antoracommand at your playbook file. In the terminal, type:
demo-site $ antora site.yml
First, 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
antoracommand again, this time with the
demo-site $ antora --stacktrace site.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.urlproperty is not defined in your playbook.
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.
When Antora runs the first time, it will cache resources in a cache directory. Antora caches two types of resources:
cloned git repositories
downloaded UI bundles
These resources are stored inside the cache directory, organized under the content and ui folders, respectively.
The default cache directory varies by operating system.
You can override the default cache location using the runtime.cache_dir key in the playbook, the --cache-dir CLI option, or the
$ANTORA_CACHE_DIR environment variable.
If you want to update the cache on subsequent runs, pass the --pull switch to the Antora CLI. 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 remote.
If you want to clear the cache altogether, you’ll need to locate the Antora cache directory on your system and delete it.
Antora supports connecting to private repositories using SSH or HTTP/HTTPS.
If your playbook is configured to fetch private repositories via SSH, you must run an SSH agent with the identity (i.e., SSH key) you’ve linked to your account on the git host. If the SSH agent isn’t running, or your key and account don’t match, Antora will fail when it attempts to clone the private repository.
Antora can also authenticate with a private repository over HTTP/HTTPS. See Connect to a private repository using HTTP authentication to learn more.
Since Antora generates static sites, you do not need to publish the site to a server in order to preview it.
To view the site, navigate to any HTML page inside the destination folder in your browser. If your using the Demo, look for the file /demo-site/build/site/index.html.
A site generated by Antora is designed to be viewable without a web server. However, you may need to view your site through a web server to test certain features, such as indexified URLs or caching. You can use the serve package for this purpose.
Install the serve package globally using npm:
demo-site $ npm i -g firstname.lastname@example.org
That puts a command by the same name on your PATH.
|We specifically recommend using serve 6.5.8 since that’s the last version known to work reliably.|
Now launch the web server by pointing it at the location of the generated site.
In the terminal, type
After executing the command, a the local address should be displayed in your terminal.
demo-site $ serve build/site
You should see the following output in your terminal.
┌─────────────────────────────────────────────────┐ │ │ │ Serving! │ │ │ │ - Local: http://localhost:5000 │ │ - On Your Network: http://192.168.1.9:5000 │ │ │ │ Copied local address to clipboard! │ │ │ └─────────────────────────────────────────────────┘
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.
Antora is designed to create sites that run anywhere, whether it be a static web host or the local filesystem. However, some hosts offer “features” that interfere 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.
Since Antora already produces a ready-made site, there’s no need for this.
It’s also 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
_, which Jekyll subsequently erases.
As a result, no UI.
Antora also puts images in a folder named
_images inside each module, so no images either.
Fortunately, there’s a way to disable this “feature” of GitHub Pages. The solution is to add a .nojekyll file to the root of the published site. Simply create an empty .nojekyll file in the output directory before committing the files to GitHub Pages.
$ touch build/site/.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 (and will be available sooner).