Organizing Your Documentation for Antora

Antora works with collections of documentation that follow a standard, well-defined project structure. The benefits of a standard project structure for documentation are as follows:

  • faster onboarding of contributors

  • interoperability with authoring, validation, migration, and bootstrap tools

  • the ability to define page references that span component versions (and thus repositories), are not coupled to output URLs (source-to-source), and can be automatically updated by a tool when source files are moved and renamed

  • better organization system to manage files as the documentation grows

We call a collection of documentation files organized under Antora’s standard project structure a documentation component.

When you use documentation components, you can take advantage of the open source tools, plugins, and automated processes built to integrate with the Antora pipeline.

Documentation component overview

A documentation component is content that adheres to a standard, well-defined organization structure. This type of component contains of a collection of AsciiDoc text files and their assets, such as images, as well as a component descriptor file. All the documentation in a component should follow the same versioning scheme and be versioned together. Your site can be generated using just one documentation component, or as many as you want.

When Antora receives instructions from your playbook to scan a specific repository, its first objective is to find a component descriptor file in that repository. The component descriptor file is named antora.yml.

Once Antora finds this file, it assumes that that directory and all its files and subdirectories are a documentation component. The structure of a documentation component is laid out below.

component dir structure

The component illustrated in the above figure contains required and reserved directories and files as well as an example of an optional, user created module (user-named-module). When Antora encounters these folders and files in a properly structured component, it automatically assigns preset behavior and metadata to them.

Component preset legend

Required - Must be present in the documentation component.

Optional - Doesn’t need to be created if the directory, file, or content type isn’t applicable to the component or module.

Reserved - Directory or file is associated with specific pipeline operations. The contents of a directory or file using a reserved name must adhere to certain requirements.

antora.yml

Required; Reserved

The component descriptor file tells Antora that the contents of the directory are a documentation component. This file contains crucial metadata about the documentation component.

modules

Required; Reserved

Except for antora.yml, all of the files in a component reside in this directory.

modules/ROOT

Required; Reserved

Directory that contains the mandatory ROOT module. The directory name must be written in all uppercase letters.

<module>/assets

Optional; Reserved

Directory where multimedia and supplemental files are organized by content type.

<module>/assets/attachments

Optional; Reserved

Directory that contains supplemental materials, such as PDFs or ZIP files, that readers can download via a link created in a page using the AsciiDoc link macro.

<module>/assets/images

Optional; Reserved

Directory that contains pictures, screenshots, diagrams, and other graphics files that are displayed in a page using the AsciiDoc image macro.

<module>/examples

Optional; Reserved

Directory that contains source, literal, listing, or example block snippets that are inserted into that module’s pages.

<module>/pages

Required; Reserved

Directory that contains all of a module’s AsciiDoc files. These files are automatically enlisted by Antora and converted to standalone HTML pages.

<module>/pages/_partials

Optional; Reserved

Directory that contains AsciiDoc files that can be inserted into the files stored directly under pages. These files are not converted to HTML by Antora directly. Instead, they must be referenced by an include directive in a page in the pages directory.

<module>/_attributes.adoc

Required; Reserved

Helper file that enables assets, partials, and examples to be rendered in preview tools such as Atom and the Asciidoctor Chrome extension.

<module>/nav.adoc

Optional; Reserved

A navigation file contains one or more AsciiDoc lists. Each navigation file must be declared in the component descriptor if you want it to be displayed in the site’s navigation panel. The order in which the navigation file contents are displayed in the panel is controlled by the order these files are listed in the nav key of the component descriptor.

modules/user-named-module

Optional

In addition to the ROOT module, you can create as many additional modules as your documentation component requires.