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