Antora Configuration Guide

1. Overview

This guide covers Antora-specific configuration, module management, and project structure. It is designed for documentation authors and AI agents working with Antora documentation sites.

For AsciiDoc formatting standards and conventions, see the AsciiDoc Style Guide. This guide focuses exclusively on Antora configuration and project structure.

2. Antora Project Structure

An Antora documentation project follows a standardized directory structure:

[project-root]/
├── antora.yml                    # Component descriptor (DO NOT recreate)
├── .ai/                          # AI guidance files
│   ├── DOCUMENTATION-GUIDE.adoc
│   ├── QUICK-START.md
│   └── MODULE-README-TEMPLATE.md
└── modules/
    ├── ROOT/                     # Default module (always present)
    │   ├── nav.adoc              # Per-module strategy: ROOT's own nav
    │   ├── nav-*.adoc            # Category-wrapper strategy: one per category
    │   └── pages/
    │       └── index.adoc
    └── {module-name}/            # Additional modules
        ├── README.md             # Optional: Module context
        ├── nav.adoc              # Per-module strategy only; omitted under category-wrapper
        ├── DEPENDENCIES.txt      # Cross-module dependency tracking
        ├── attachments/          # Binary files for download
        ├── examples/             # Code examples
        ├── images/               # Images and diagrams
        ├── pages/                # Main content pages
        │   └── index.adoc        # Module landing page
        └── partials/             # Reusable content snippets

Module Template: The module-template/ directory is maintained centrally in the doc-standard repository and NOT copied into individual projects. Fetch it from there when creating new modules.

Reserved Directory Names:

The following directory names are reserved by Antora and cannot be changed:

attachments - For downloadable files
examples - For code snippets and example files
images - For visual assets
pages - For documentation pages
partials - For reusable content fragments

3. Creating New Antora Modules

When creating a new Antora module, follow these steps carefully to ensure the module appears in the generated documentation site.

3.1. Module Creation Checklist

Create the module directory structure:

modules/{module-name}/
├── pages/
│   └── index.adoc
├── nav.adoc
├── images/
├── examples/
├── partials/
└── DEPENDENCIES.txt

Register the module in antora.yml (CRITICAL STEP):
- Read the existing antora.yml file
- Add the module’s navigation file to the nav: section
- Example:
  
  nav: - modules/ROOT/nav.adoc - modules/existing-module/nav.adoc - modules/{new-module-name}/nav.adoc # <-- Add this line
Create module documentation:
- Create pages/index.adoc as the module landing page
- Per-module strategy: create nav.adoc with at minimum * Module Name
- Category-wrapper strategy: do NOT create a module-level nav.adoc; instead add an entry for the new module to the relevant modules/ROOT/nav-<category>.adoc wrapper using fully-qualified xrefs (xref:<module>:index.adoc[])
- Create DEPENDENCIES.txt to track cross-module references
Verify the module appears:
- Build the Antora site locally
- Confirm the new module appears in navigation
- Check all xrefs resolve correctly

Module Registration is Not Optional: Every module MUST be registered in antora.yml under the nav: section. Without this, the module will exist in the file system but will not appear in the generated documentation site.

This is the #1 most commonly forgotten step when creating new modules!

3.2. Using the Module Template

The module-template/ directory is maintained centrally in the doc-standard repository root. To create a new module:

Fetch module-template/ from doc-standard repository
Copy it to modules/{new-module-name}/ in your project
Customize the files for your module
Register the module in antora.yml

# Example: Creating a new "api" module

# If doc-standard is available locally:
cp -r /path/to/doc-standard/module-template/ modules/api/

# Or clone doc-standard first:
git clone [email protected]:christhonie/doc-standard.git /tmp/doc-standard
cp -r /tmp/doc-standard/module-template/ modules/api/

# Then customize:
# Edit modules/api/pages/index.adoc
# Edit modules/api/nav.adoc
# Update antora.yml to add: - modules/api/nav.adoc

4. Navigation Strategies

Antora supports two viable strategies for organising the nav: list in antora.yml. Pick one for the project and stick to it — mixing the two creates orphan files and confuses contributors.

4.1. Per-Module Navigation

Each module owns its own modules/<module>/nav.adoc. antora.yml lists every module’s nav file:

nav:
- modules/ROOT/nav.adoc
- modules/api/nav.adoc
- modules/security/nav.adoc

xrefs inside each nav.adoc are unqualified (page.adoc) because the file lives in the module it navigates.

When to use:

Small to medium projects (under ~10 modules)
Each module is conceptually independent
The flat top-level list in the sidebar is short enough to scan at a glance

This is the default and is the strategy the rest of this guide assumes.

4.2. Category-Wrapper Navigation

Navigation is consolidated under a small set of named categories that live in modules/ROOT/. Each wrapper opens with a .Category Display Name heading and uses fully-qualified xrefs (xref:<module>:page.adoc[]) into the source modules. Source modules contain only pages/, images/, etc. — no nav.adoc.

nav:
- modules/ROOT/nav-overview.adoc
- modules/ROOT/nav-requirements.adoc
- modules/ROOT/nav-system-architecture.adoc
- modules/ROOT/nav-admin-portal.adoc
- modules/ROOT/nav-build-operate.adoc

.Admin Portal
* xref:admin-portal-design:index.adoc[Overview]
** Operation
*** xref:admin-portal-design:OrderProcessing.adoc[Order Processing]
*** xref:admin-portal-design:Pricing.adoc[Pricing]

The .Admin Portal line renders as a non-clickable category heading in the Antora UI default theme, giving the sidebar visible boundaries between groups of modules.

When to use:

Large projects (10+ modules) where a flat top-level list becomes hard to scan
Modules naturally cluster into logical groups (e.g., "Admin Portal", "Build & Operate", "Specialist Topics")
You want named section headings between groups in the sidebar without adding a fourth navigation level

Trade-offs:

Adding a page now requires editing a wrapper file in modules/ROOT/ rather than a nav file inside the module.
All cross-module xrefs in wrappers must be fully qualified — easy to forget.
Adding a new module requires choosing a category and editing the right wrapper.

Worked example: the event component in docs-event consolidates 22 modules into 10 category wrappers. See modules/ROOT/nav-*.adoc in that repo for a reference layout.

5. Navigation File Structure

Antora navigation files (nav.adoc) create the left-hand navigation menu. The structure uses hierarchical lists to create collapsible sections. The same level/list rules below apply within either navigation strategy — the difference is only where the file lives and whether xrefs are qualified.

5.1. Three-Level Hierarchical Structure

Use this structure for modules with logical subsections:

* xref:index.adoc[Module Name]
** Section Heading 1
*** xref:page1.adoc[Page 1]
*** xref:page2.adoc[Page 2]
** Section Heading 2
*** xref:page3.adoc[Page 3]
*** xref:page4.adoc[Page 4]

Rendered Navigation:

Module Name (level 1) - Clickable link to index.adoc, collapsible section
- Section Heading 1 (level 2) - Non-clickable label for grouping
  - Page 1 (level 3) - Clickable link
  - Page 2 (level 3) - Clickable link
- Section Heading 2 (level 2) - Non-clickable label for grouping
  - Page 3 (level 3) - Clickable link
  - Page 4 (level 3) - Clickable link

Example:

* xref:index.adoc[System Components]
** Architecture
*** xref:component-architecture.adoc[Component Architecture]
*** xref:component-dependencies.adoc[Component Dependencies]
** Component Categories
*** xref:database-components.adoc[Database Components]
*** xref:backend-services.adoc[Backend Services]
*** xref:frontend-applications.adoc[Frontend Applications]

5.2. Two-Level Simplified Structure

For modules with simple navigation (only one section heading), flatten the structure to two levels:

* xref:index.adoc[Module Name]
** xref:page1.adoc[Page 1]
** xref:page2.adoc[Page 2]
** xref:page3.adoc[Page 3]

When to Use:

Module has 5 or fewer pages
Pages don’t naturally group into logical sections
Content is simple and doesn’t require subsections

When to Upgrade to Three Levels:

Module grows beyond 5-6 pages
Pages can be grouped into 2 or more logical sections
Better organization improves user navigation

Example:

* xref:index.adoc[Deployment]
** xref:local-deployment.adoc[Local Deployment]
** xref:production-deployment.adoc[Production Deployment]
** xref:docker-deployment.adoc[Docker Deployment]

5.3. Navigation Hierarchy

Level 1 (*):

Module name
Links to module’s index.adoc
Creates collapsible section in navigation
Use module name as displayed in the menu (e.g., "Domain Entities", "System Components")

Level 2 (**):

For three-level: Section heading (non-clickable label)
For two-level: Page links
Groups related pages logically
Use clear, concise labels (e.g., "Architecture", "Reference")

Level 3 (*):

Individual page links
Only used in three-level navigation
Actual documentation pages

Navigation Best Practices:

Use sentence case for navigation entries
Keep navigation labels concise (under 40 characters)
Organize logically by topic or workflow
Link module name to index.adoc (overview page)
Use section headings for grouping (level 2 in three-level structure)
Avoid navigation depth beyond 3 levels
Start with two-level structure, add third level when module grows
Maintain consistency across similar modules

6. Cross-References

6.1. Internal Module References

Reference pages within the same module:

xref:other-page.adoc[Link Text]

xref:other-page.adoc#section-id[Link to Section]

6.2. Cross-Module References

Reference pages in other modules:

xref:module:page.adoc[Cross-module Link]

xref:api:authentication.adoc[Authentication Guide]

6.3. Cross-Component References

Reference pages in other components (with version):

xref:version@component:module:page.adoc[Cross-component Link]

xref:1.0@product:api:rest-api.adoc[REST API v1.0]

6.4. Component Versions

Reference specific versions in cross-references:

xref:1.0@component:module:page.adoc[Link to Version 1.0]

xref:latest@component:module:page.adoc[Link to Latest]

Always use xref: syntax for internal documentation links. Never use relative file paths or hardcoded URLs.

7. Antora Attributes

Common Antora attributes for use in content:

{page-component-title} - Current component title
{page-component-version} - Current version
{page-module} - Current module name
{page-origin-url} - Source file URL

Usage Example:

This page is part of the {page-component-title} component, version {page-component-version}.

8. Module Dependency Tracking

Each module MUST maintain a DEPENDENCIES.txt file in its root directory to track cross-module references. This file serves as a dependency tracking mechanism.

8.1. DEPENDENCIES.txt Format

# Module Dependencies for {module-name}

This file tracks which other documentation modules are referenced by {module-name}.
Keep this updated when adding cross-module references using xref.

## Direct Dependencies

### {referenced-module-name}
- **Referenced in:** pages/security.adoc, pages/index.adoc
- **Reason:** Brief explanation of why this dependency exists
- **Key references:**
  - xref:{module}:path/to/page.adoc[] - Description
  - xref:{module}:partial$filename.adoc[] - Description (if using partials)

## Transitive Dependencies

{referenced-module} → {another-module}
Brief explanation of transitive relationship

## Usage Guidelines

When adding a new xref to another module:
1. Add the module name to "Direct Dependencies" if not already present
2. List the specific file being referenced
3. Explain why the reference is needed
4. Update this file in the same commit

## Circular Dependency Check

- ✓ No circular dependencies detected
- {other-module} does NOT reference {this-module}

8.2. When to Update DEPENDENCIES.txt

ALWAYS update DEPENDENCIES.txt when you:

Add an xref to another module (e.g., security:index.adoc)
Include a partial from another module (e.g., include::security:partial$jwt-flow.adoc[])
Reference images from another module
Add any cross-module reference

Example:

If you add this reference in registration-portal/pages/security.adoc:

See xref:security:authentication/jwt-authentication.adoc[JWT Authentication]

Then update registration-portal/DEPENDENCIES.txt:

### security
- **Referenced in:** pages/security.adoc
- **Reason:** JWT authentication flow documentation
- **Key references:**
  - xref:security:authentication/jwt-authentication.adoc[] - JWT auth flow

8.3. Circular Dependency Prevention

Before adding a cross-module reference:

Check if it would create a circular dependency
Document any transitive dependencies
If circular dependency is unavoidable, consider:
- Creating a new shared module
- Using partials to extract common content
- Restructuring the dependency graph

9. antora.yml Configuration

The antora.yml file is the component descriptor that defines the documentation component.

9.1. Understanding antora.yml

DO NOT recreate or regenerate this file. It already exists and contains critical configuration.

Structure:

name: component-name
title: Component Display Name
version: '1.0'
nav:
- modules/ROOT/nav.adoc
- modules/module1/nav.adoc
- modules/module2/nav.adoc

9.2. When to Modify antora.yml

antora.yml Modification Rules:

✅ DO: Update the nav: section when adding new modules
❌ DO NOT: Recreate or regenerate the entire file
❌ DO NOT: Modify component name, version, or other metadata without discussion
❌ DO NOT: Change the file format or structure

Example of correct update:

# Before
nav:
- modules/ROOT/nav.adoc

# After (added new module)
nav:
- modules/ROOT/nav.adoc
- modules/api/nav.adoc  # Correctly added

10. Common Pitfalls

10.1. Forgetting to Register New Modules

Problem: Creating a new module directory but forgetting to add it to antora.yml.

Symptom: Module files exist, but don’t appear in the documentation site navigation.

Solution: Always update antora.yml when creating a new module:

nav:
- modules/ROOT/nav.adoc
- modules/your-new-module/nav.adoc  # Don't forget this!

AI Agent Note: The guidance "DO NOT modify antora.yml" refers to not recreating or regenerating the file. You MUST update it to register new modules in the nav: section.

10.2. Broken Cross-References

Problem: Cross-references not resolving correctly.

Solutions:

Verify xref syntax: Link Text
Check that target file exists in correct module/component
Ensure file extension is included (.adoc)
For cross-module refs, use correct syntax: Text

10.3. Missing Module Dependencies

Problem: Not tracking cross-module dependencies.

Solution: Always update DEPENDENCIES.txt when adding cross-module references.

11. Module README Template

Each module root can contain a README.md to help developers understand the module’s purpose.

See .ai/MODULE-README-TEMPLATE.md at the project root for a customizable template.

# {Module Name} Documentation Module

## Purpose

Brief description of what this module documents.

## Structure

- `pages/` - Main documentation content
- `images/` - Diagrams and screenshots
- `examples/` - Code examples
- `partials/` - Reusable content snippets

## Dependencies

See `DEPENDENCIES.txt` for cross-module references.

## Contributing

Guidelines for contributing to this documentation module.

## AI Documentation

This project uses AI-assisted documentation generation. See the `.ai/` folder
at the project root for AI guide files.

12. Quality Checklist

Before finalizing Antora configuration changes, verify:

Module Structure:

Module directory follows Antora standards
All required directories are present (pages/, nav.adoc)
Module has an index.adoc landing page
DEPENDENCIES.txt created and maintained

Module Registration:

NEW MODULE: Module registered in antora.yml (most critical!)
Navigation file (nav.adoc) created and properly formatted
Module appears in site navigation after build

Cross-References:

All xrefs use correct Antora syntax
Cross-module references documented in DEPENDENCIES.txt
No circular dependencies created
All xrefs resolve correctly

Navigation:

Navigation structure is logical and hierarchical
Navigation labels are clear and concise
Appropriate hierarchy level (2 or 3 levels)

13. Additional Resources

Antora Documentation
Antora Cross-Reference Guide
Antora Navigation Documentation
Component Descriptor (antora.yml)
AsciiDoc Style Guide - For content formatting standards

This guide ensures proper Antora configuration and module management.