A documentation component is composed of one or more modules. A module is a discrete bundle of content, including text, images, and other source materials, organized in a hierarchy of folders by content type, then by optional topic (aka tag or category) if needed.
You might be contemplating one or more of the following questions:
Why have modules?
Do we need all this structure?
Isn’t a component enough?
One thing we’ve learned about documentation is that it multiplies, often quickly and unpredictably. As more content is created and your documentation team grows, more often than not, you want to start grouping files into folders to make them easier to find and manage. Modules allow you to group text files and their associated assets together as your documentation expands, all while preserving the full capability of Antora’s page ID.
Modules are also perfect when one software project is incubating a potential subproject that may spin off as its own project in the future. It’s easy to later detach a module from a component and set it up as its own documentation component.
A documentation component must have at least one module, named ROOT. In addition to the ROOT module, you can create as many additional modules in a component as you need. All of a component’s modules must be stored in modules.
The following figure illustrates a documentation component with a few example folders and files added for context. Let’s examine the role of each module subdirectory and any associated requirements.
We’ll start with the ROOT module, since it’s required.
A documentation component must contain a ROOT module directory.
The ROOT module contains all the content that’s directly associated with the documentation component itself. When the pages in the ROOT module are published, these pages are promoted a level above any other modules' pages in that component’s URL. (You can see an example of a ROOT page’s URL in pages.) The directory name, ROOT, must be entered in all uppercase letters. When used in a page reference, it must be entered in all uppercase letters.
Small documentation components may never need more than a ROOT module. However, if your project grows, you can easily add more modules and gradually redistribute the content without having to restructure the project. So while the extra structure seems like overkill now, in the long run, you’ll be glad you gave your content the space to grow.
The ROOT module, as well as any other modules you create, should include the appropriate content type subdirectory when a module uses that content type.
AsciiDoc documents go in the pages folder.
Images go in the assets/images folder.
Code snippets go in the examples folder.
Each one of these folders can have an arbitrary depth of topic folders that are used to group files to make them easier for you to manage and navigate.
When a writer is working on the content, the module becomes the writer’s primary workspace. The writer doesn’t have to look elsewhere to find files that belong together. This arrangement mirrors how software developers work on source code.
Let’s look at each of these directories and their content type in more detail.
Any attachment, image, and video files associated with a module must be stored in the corresponding content or media type subdirectory under that module’s assets directory.
The subdirectory names automatically recognized by Antora and associated to the corresponding AsciiDoc macros are:
You don’t need to set the path to these three subdirectories in the header of your AsciiDoc files. This is managed automatically by Antora. When viewing the file in a preview tool, such as Atom or the Asciidoctor Chrome extension, the path is managed by the adjacent _attributes.adoc file.
An attachment is a resource that you want your user to download, such as a PDF or a ZIP archive of a sample project. Attachment files are saved in assets/attachments in the same module where the page that links to that file is located.
A link to an attachment is created in a page using the AsciiDoc link macro.
Image files are saved in assets/images in the same module where the page that references that image is located. We also recommend that you mirror the topic hierarchy of the page in which the image is referenced, if the image belongs to a specific page.
Common image file formats include:
GIF (static and animated)
Images are inserted into a page using the AsciiDoc image macro (block or inline).
Self-hosted video files are saved in assets/videos in the same module where the page that references that video is located. Videos are inserted into a page using the AsciiDoc video macro.
The examples directory can contain non-AsciiDoc file types, such as source code or data values. These files are often inserted into listing blocks using the AsciiDoc include directive.
AsciiDoc document files that are destined to become standard pages are stored in the pages folder of a module. These files are converted to HTML and automatically published as standalone pages in the generated site.
When the pages in the ROOT module are published, these pages are promoted a level above any other modules’ pages in that component’s URL.
Let’s say the component illustrated above is the documentation for your newest software product, Hyper Lemur. What would the URL for modules/ROOT/pages/deploy.adoc look like?
The base URL is set in the playbook. The component name, in this case hyperlemur, is set in the component descriptor. The page name segment is the basename of the AsciiDoc file. Notice that the name of the module, ROOT, isn’t in the URL. Files that are stored directly in the ROOT folder are published at the root of the component.
In contrast, pages that are stored in other modules (i.e., not in ROOT), will be preceded by the name of the module. Let’s see what the URL for modules/a-module/pages/user-management.adoc would look like.
The module name is the name of the module directory where that page is stored.
Don’t set the path to the _partials directory in the header of the AsciiDoc file. This is managed automatically by Antora. When viewing the file in a preview tool, the path is managed by the adjacent _attributes.adoc file.