Run Antora to Generate Your Site

Assumptions:

On this page, you’ll learn:

  • How to run the default Antora pipeline.

  • How to preview a generated site locally.

Antora Demo

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 provide a default UI bundle. As soon as you’ve installed Antora, you can use it with the Demo materials and explore its capabilities.

Choose a Playbook

To produce a documentation site, Antora needs a playbook.

First, create a new directory for your site and switch to it. For the examples on this page, we’ll use the demo materials.

Open a terminal and make a new directory named demo-site. Then switch into that directory.

$ mkdir demo-site
$ cd demo-site

Next, create a new playbook file named demo-site.yml and populate it with the contents of the following source block. You can also download this playbook from the demo-site repository.

demo-site.yml
site:
  title: Antora Demo Site
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: master
    start_path: docs
ui:
  bundle: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable

Save the playbook.

Run Antora

To generate the site with the default pipeline, point the antora command at your playbook file.

In the terminal, type:

$ antora demo-site.yml

Antora will clone the content repository, convert the AsciiDoc pages to embeddable HTML, wrap the HTML in the page template from the UI, then assemble the pages together with the assets under the destination folder, which defaults to build/site.

The repositories are cached under the build/site directory. If you remove the build directory, the repositories will have to be downloaded again the next time you run antora demo-site.yml.

Private GitHub repositories

If your playbook uses private repositories, you must have an SSH agent running with the identity (i.e., SSH key) you’ve linked to your GitHub account. Otherwise, Antora will fail.

The SSH agent allows Antora to authenticate with private repositories on your behalf. To learn how to generate an SSH key, start the SSH agent, add your identity, and add your SSH key to your GitHub account, please refer to the article Generating a new SSH key and adding it to the ssh-agent.

Local Site Preview

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/demo-component-b/index.html.

Optional: Run local server

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:

$ npm i -g serve

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:

$ serve build/site

Paste the provided URL into the location bar of your browser and you’ll be viewing your site through a local web server.