darling docs

Building an Antora site I

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:

  1. Antora can retrieve content and source files from multiple git repositories.
  2. Content is written in AsciiDoc—a readable, extensible, and easy to learn markup language.
  3. The workflow is designed to encourage a docs-as-code approach to content authoring.

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.

Introduction to Antora

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.

Source files

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 Antora config file.

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

Required files

In addition to the hierarchy, Antora requires several files (and folders) in order to process the incoming content correctly. These files are:

  1. The 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.

  2. The 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 modules folder.

The modules and 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.

My quick build

  1. Create and organize a git repository according to a chosen directory structure. Remember content files are in .adoc format.

  2. Follow the Antora Quickstart.

    • Check for Node. In my case, I did not have Node installed, so followed the directions to install nvm on Windows using Chocolatey.

Before proceeding further ensure the node --version is 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.2 did not set the LTS version as default. If this happens, try nvm use 12.16.2 to set the default version. Only when the nvm version is set will the Antora install work.

  1. Create a playbook file.
    • The playbook file listed in the quickstart will generate a website using the Antora Demo GitLab repositories. To open a different git repository, populate the antora-playbook.yml file 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`>

  1. Populate an 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 the required name and version attributes, as shown here.

  2. Run Antora! Follow the final quickstart step to build the site.

Final thoughts

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.