I had previously provided some documentation for a local server build project. For this project, we used Antora to host the scripts and versioned docs.
Antora is a static site generator used to create and publish technical documentation. The three featues that make Antora particularly useful for complex projects are:
Below are details of my experiences with a very simple Antora build as a guide for future projects. Further details of Antora’s functionality can be found in their documentation.
A static site generator (SSG) takes a collection of source files, processes them using the necessary templates and data, then creates HTML an output which can be presented at a specified URL. As with other SSGs, Antora does this well, but also provides robust cross-referencing features and content reuse.
All source files for the documentation build are stored in one or more git repositories. These
repos can be owned by different people. The location of the project repos are indicated in the
The Antora content source files are organized in a very specific hierarchy. This directory structure—and its reserved names—are necessary for Antora to understand which files to collect; the classification of these files; what their intended roles are; and their inclusion or exclusion from the web presentation. Here are four examples of how the content source files can be organized.
For this project, I chose to organize the repository files in the following structure:
Repository └── docs folder ├── antora.yml file └── modules folder └── ROOT folder └── pages folder └── index.adoc └── content folder ├── nav.adoc file └── pages folder └── content-files.adoc └── images folder
In addition to the hierarchy, Antora requires several files (and folders) in order to process the incoming content correctly. These files are:
antora-playbook.yml file: This file is the
config file and includes key information about
the content location, including repository branches, naming conventions, and other global metadata.
antora.yml file: When Antora builds the HTML site, the program requires this file to further
process and unpack the subsequent content. This file must be contained in a location with the
ROOT folders are important for the hierarchy and presentation of content files. For example, by
default Antora will look for an
index.adoc file in the
ROOT folder. Additional module folders can be assigned
names and subfolders for project personalization.
Create and organize a git repository according to a chosen directory structure. Remember content files are in
Follow the Antora Quickstart.
Before proceeding further ensure the
12.16.2. During my build I received an error saying
The term 'npm' is not recognized...when trying to install Antora. The suggested setting
nvm alias default 12.16.2did not set the LTS version as default. If this happens, try
nvm use 12.16.2to set the default version. Only when the nvm version is set will the Antora install work.
antora-playbook.ymlfile with these changes:
title: <Choose a title> content: sources: #enter a source per linked repository - url: https://<the URL path to the repository>.git branches: <branch information> start_path: <the beginning repo folder that contains the `antora.yml` file, for example, `docs`>
antora.yml file in your git repository. There are many optional keys you can include in the
antora.yml file, but make sure you include
version attributes, as shown here.
Run Antora! Follow the final quickstart step to build the site.
Antora is a very technical SSG with optional keys, additional attributes, and personalization. Their documentation includes information
on how to link
nav to the
antora.yml file, cross referencing and page IDs, and much more.
I hope to add to this mini guide in the future as the server documentation site grows.
A final note: When making changes to the git repository, the Antora build will need to be
fetched. When Antora perfoms an initial build, the cloned git repository is cached. To refresh, try using
$ antora generate --fetch antora-playbook.yml.