Antora Documentation System

1. Overview

Antora is the documentation platform for Domus Digitalis infrastructure. It enables:

  • Multi-component sites — separate repos, unified output

  • Team collaboration — each team owns their component

  • Single source of truth — attributes defined once, used everywhere

  • Cross-component linking — seamless navigation between projects

2. Architecture

Hub-Spoke Documentation Architecture

The hub-spoke model separates orchestration (domus-docs) from content (component repositories). Each component defines its own antora.yml with a unique namespace, enabling cross-component linking via xrefs.

Table 1. Active Components
Component Namespace Description

domus-infra-ops

infra-ops::

Infrastructure operations, services, runbooks

domus-ise-linux

prj-ise-home-linux::

Linux 802.1X EAP-TLS deployment

domus-netapi-docs

netapi::

Network automation CLI documentation

domus-secrets-ops

secrets-infrastructure::

Secrets management with SOPS and age

3. Component Structure

Each documentation component follows this structure:

repo/
├── Makefile                    # Root build commands
├── README.adoc                 # Project overview
├── runbooks/                   # Standalone PDF export
│   ├── _partials/              # Attributes for standalone builds
│   └── *.adoc                  # Operational runbooks
├── scripts/                    # Build tools
│   └── build-adoc.sh
└── docs/asciidoc/              # Antora component
    ├── antora-playbook.yml     # Site playbook (local builds)
    ├── antora.yml              # Component descriptor
    └── modules/ROOT/
        ├── nav.adoc            # Navigation tree
        ├── pages/              # Documentation content
        ├── partials/           # Reusable snippets
        │   └── diagrams/       # Parameterized diagrams
        ├── images/             # Static images
        ├── examples/           # Code examples
        └── attachments/        # Downloadable files

4. Component Descriptor (antora.yml)

The antora.yml file defines the component and its attributes:

name: infra-ops                          # Component name (used in URLs)
title: Infrastructure Operations         # Display title
version: '2026'                          # Version string
start_page: ROOT:index.adoc              # Landing page
nav:
  - modules/ROOT/nav.adoc                # Navigation file

asciidoc:
  attributes:
    # All parameterized values go here
    domain: inside.domusdigitalis.dev
    pfsense-ip: 10.50.1.1
    ise-01-ip: 10.50.1.20
    # ... 100+ attributes

5. Build Output

After running make site:

docs/asciidoc/build/site/
├── index.html                  # Site landing page
├── infra-ops/                  # Component: domus-infra-ops
│   ├── 2026/                   # Version
│   │   ├── index.html          # Component index
│   │   ├── architecture/       # Section pages
│   │   ├── services/
│   │   ├── runbooks/
│   │   └── ...
├── ise-linux/                  # Component: domus-ise-linux
│   └── ...
├── _/                          # Antora UI bundle
│   ├── css/
│   ├── js/
│   └── img/
├── sitemap.xml                 # Search engine sitemap
└── 404.html                    # Error page

6. Team Collaboration Models

6.1. Model 1: Single Repo, Multiple Modules

One repository with separate modules per team:

project-docs/
└── docs/asciidoc/modules/
    ├── ROOT/           # Core documentation (architecture, glossary)
    ├── network/        # Network team owns this module
    │   ├── nav.adoc
    │   └── pages/
    ├── security/       # Security team owns this module
    │   ├── nav.adoc
    │   └── pages/
    └── linux/          # Linux team owns this module
        ├── nav.adoc
        └── pages/

Each module has its own nav.adoc and pages/ directory. Teams work independently within their module.

Ready-to-use template: See Team Module Template for complete file templates, cross-linking examples, and setup checklist.

6.2. Model 2: Multi-Repo Components (Current)

Each team owns their repository:

Repository Owner Content

domus-infra-ops

Infrastructure team

Architecture, services, recovery, incidents

domus-ise-linux

Security/NAC team

Linux EAP-TLS methodology (portable)

PRJ-ISE-CHLA-LINUX-ANTORA

CHLA project team

CHLA-specific deployment

A central playbook pulls all components into one site.

6.3. Model 3: Hybrid

Core documentation in main repo, specialized topics in separate repos:

# antora-playbook.yml
content:
  sources:
    # Main repo with multiple modules
    - url: https://github.com/you/domus-infra-ops
      start_path: docs/asciidoc

    # Specialized repo (single component)
    - url: https://github.com/you/domus-ise-linux
      start_path: docs/asciidoc

7. Cross-Component Linking

7.1. Same Component

Link within the same component:

// Relative link (same module)
See xref:runbooks/disaster-recovery.adoc[Disaster Recovery]

// Link to another section
See xref:services/pfsense/overview.adoc[pfSense Overview]

7.2. Different Component

Link to another component using the component name:

// Link to ise-linux component
See xref:ise-linux::04-linux-client/networkmanager-wired.adoc[NetworkManager Setup]

// Format: xref:component::path/to/page.adoc[Link Text]

7.3. Different Version

Link to a specific version:

// Link to 2025 version
See xref:2025@infra-ops::runbooks/pki-strategy.adoc[PKI Strategy (2025)]

8. Parameterized Content

8.1. Attributes in antora.yml

All values are defined as attributes:

asciidoc:
  attributes:
    # Infrastructure
    pfsense-ip: 10.50.1.1
    ise-01-ip: 10.50.1.20

    # VLANs
    vlan-mgmt: 100
    vlan-research: 40

    # Policy names
    policy-set-wired: Wired_802.1X_Closed

8.2. Using Attributes in Pages

The pfSense firewall is at `{pfsense-ip}`.

ISE primary node: `{ise-01-ip}`

Research workstations use VLAN `{vlan-research}`.

8.3. Parameterized Diagrams

Diagrams can use attributes with subs=attributes+:

[d2,network-topology,svg,subs=attributes+]
....
pfsense: pfSense {
  label: "{pfsense-ip}"
}

ise: ISE {
  label: "{ise-01-ip}"
}

pfsense -> ise: "RADIUS"
....

When attributes change in antora.yml, all diagrams update automatically.

9. Build Commands

Command Description

make

Build Antora site (default)

make site

Build Antora site

make runbook-pdf

Export standalone runbook PDFs

make all

Build site + export runbooks

make clean

Remove build artifacts

make help

Show all targets

10. Multi-Site Playbook

To build a unified site from multiple repos, create a central playbook:

# antora-playbook.yml (in a dedicated repo or root level)
site:
  title: Domus Digitalis Documentation
  start_page: infra-ops::index.adoc

content:
  sources:
    - url: https://github.com/EvanusModestus/domus-infra-ops
      branches: main
      start_path: docs/asciidoc

    - url: https://github.com/EvanusModestus/domus-ise-linux
      branches: main
      start_path: docs/asciidoc

ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true

output:
  dir: ./build/site

Build with:

npx antora antora-playbook.yml

11. Hosting Options

Option Pros Cons

GitHub Pages

Free, automatic from repo

Public only (free tier)

Netlify

Free tier, preview deploys

Build minutes limited

Self-hosted (nginx)

Full control, private

Maintenance overhead

GitLab Pages

Integrated CI/CD

GitLab-specific

12. Workflow Summary

  1. Edit content in docs/asciidoc/modules/ROOT/pages/

  2. Update attributes in antora.yml when values change

  3. Build locally with make site

  4. Preview at docs/asciidoc/build/site/index.html

  5. Commit and push

  6. CI/CD builds and deploys (if configured)

13. Related Documentation