Antora Reference

Antora documentation site generator. Components, playbooks, module structure, navigation, attributes, and build workflow.

Component Descriptor

antora.yml — defines a documentation component

name: captures
title: Captures
version: ~
nav:
  - modules/ROOT/nav.adoc
asciidoc:
  attributes:
    icons: font
    experimental: ''
    source-highlighter: highlight.js

The version: ~ disables versioning (single-version component). All attributes declared here are available in every page via {attribute-name}.

Playbook

antora-playbook.yml — the hub aggregator config

site:
  title: Domus Digitalis
  url: https://docs.domusdigitalis.dev
content:
  sources:
    - url: https://github.com/user/domus-captures.git
      branches: main
      start_path: docs
    - url: https://github.com/user/domus-infra-ops.git
      branches: main
      start_path: docs
ui:
  bundle:
    url: ./ui-bundle.zip

Each source is a spoke repo. The hub (domus-docs) aggregates them. Push a spoke to deploy; push the hub only for playbook or UI changes.

Module Structure

Standard Antora module layout

docs/
├── antora.yml              (1)
└── modules/
    └── ROOT/               (2)
        ├── nav.adoc        (3)
        ├── pages/          (4)
        ├── partials/       (5)
        ├── examples/       (6)
        ├── images/         (7)
        └── attachments/    (8)

1	Component descriptor with attributes
2	Default module — no module prefix needed in xrefs
3	Navigation tree (or use partials for modular nav)
4	Published pages — each `.adoc` becomes a URL
5	Reusable content fragments — `include::partial$name.adoc[]`
6	Code examples — `include::example$path/file.adoc[]`
7	Images — `image::path/file.png[]`
8	Downloadable files — `../../_attachments/file.pdf`

Navigation

nav.adoc — tree structure with xrefs

* Category
** xref:page.adoc[Page Title]
** Subcategory
*** xref:sub/page.adoc[Sub Page]

Modular navigation — split nav into partials

// nav.adoc
include::partial$nav/chronicles.adoc[]
include::partial$nav/knowledge-base.adoc[]
include::partial$nav/projects.adoc[]

Each partial owns its section of the nav tree. Changes are localized.

Attributes Workflow

Check before using — never assume an attribute exists

grep -i "domain" docs/antora.yml
# Output:
#     domain: inside.domusdigitalis.dev

Add a new attribute to antora.yml

asciidoc:
  attributes:
    new-hostname: srv-new.inside.domusdigitalis.dev

Use in pages — bare in prose, subs in code blocks

Connect to {new-hostname} for the service.

 [source,bash,subs=attributes+]
 ----
 ssh admin@{new-hostname}
 ----

Local Build

Build and check for warnings

cd ~/atelier/_bibliotheca/domus-docs
make 2>&1 | grep -E "WARN|ERROR"

Build and serve locally

make serve
# Starts local server on port 8000
# http://localhost:8000

Build with Kroki diagrams

make            # all: diagrams local kroki-stop
make serve      # diagrams local kroki-stop serve

Kroki starts a local container for diagram rendering, then stops after build.

Troubleshooting

Common build warnings and fixes

WARNING: skipping reference to missing page: codex/missing.adoc

Fix: create the page, or remove the xref from nav and content.

WARNING: target of xref not found: component::page.adoc

Fix: verify component name matches name: in that repo’s antora.yml. Double colon (::) required for cross-component xrefs.

Attribute missing warning

WARNING: skipping reference to missing attribute: nonexistent

Fix: add the attribute to antora.yml or correct the spelling.