Antora Patterns

Antora multi-repo patterns I’ve actually used. Every entry has a date and context.

2026-03-19: xref Resolution in Nested Directories

Problem: Relative xrefs like xref:capitulo-001.adoc[] failed to resolve in subdirectories

Context: Don Quijote chapter navigation, deeply nested pages under education/literature/quijote/primera-parte/

The Fix:

// WRONG — relative xref fails in subdirectories
xref:capitulo-001.adoc[I]

// RIGHT — full path from pages/ root
xref:education/literature/quijote/primera-parte/capitulo-001.adoc[I]

Rule: Antora xrefs MUST use full paths from pages/ root in nested directories. Never assume relative resolution.

Worklog: WRKLOG-2026-03-19

2026-03: Partials for Single Source of Truth

Problem: Same table (VLAN, system inventory) appeared in 5+ pages — updates required editing every copy

Context: domus-infra-ops, duplicate data across documentation pages

The Fix:

// Extract table to partial
// partials/vlan-table.adoc — edit once, used everywhere

// Include in any page
include::partial$vlan-table.adoc[]

// Cross-component include (from another repo)
include::infra-ops::partial$vlan-table.adoc[]

Rule: If content appears in 2+ pages, extract to a partial immediately. Single source of truth prevents drift.

2026-03: Cross-Component xrefs (Double Colon)

Problem: xref to page in another Antora component failed silently

Context: Linking from domus-captures to domus-infra-ops

The Fix:

// WRONG — single colon only works within same component
xref:infra-ops:runbooks/vyos.adoc[VyOS]

// RIGHT — double colon for cross-component
xref:infra-ops::runbooks/vyos.adoc[VyOS]

Rule: Cross-component xrefs require DOUBLE colon after component name. Single colon is same-component, different module.

2026-04-04: Attribute Renaming with Downstream Propagation

Problem: Renamed pfsense-ip to vyos-vip in antora.yml but pages using 10.50.1.1 silently rendered literal text instead of the IP

Context: domus-docs hub audit — VyOS replaced pfSense 2026-03-07, attribute name was stale

The Fix:

# 1. Find all consumers BEFORE renaming the attribute
grep -rn 'pfsense-ip' docs/ --include='*.adoc'

# 2. Rename in antora.yml
# pfsense-ip: 10.50.1.1  →  vyos-vip: 10.50.1.1

# 3. Update every consumer
# {pfsense-ip}  →  {vyos-vip}

# 4. Build and verify no unresolved attributes
make 2>&1 | awk '/WARN|ERROR/'

Rule: Renaming an Antora attribute is a two-step operation: rename the definition AND grep for every consumer. With attribute-missing: skip configured, broken references fail silently — they render as literal {old-name} text with zero warnings.

Session: SESSION-domus-docs-refactor-2026-04-04

2026-04-04: Triple Playbook Synchronization

Problem: domus-gabriel-docs existed in local and CI playbooks but not production — component-count attribute said 16, landing page said 15

Context: domus-docs hub — removing a component that was never in production

The Fix:

# Audit all three playbooks for the component
grep -l 'gabriel' antora-playbook*.yml

# Remove from BOTH local and CI (production never had it)
# Also check: D2 diagrams, spoke registries in domus-captures, nav entries

# Verify component count matches reality
grep -c 'url:' antora-playbook.yml  # count actual sources
grep 'component-count' docs/antora.yml  # check declared count

Rule: When adding or removing components, touch ALL THREE playbooks (local, production, CI) and verify the component-count attribute matches. Drift between playbooks causes build differences between local and production.

Session: SESSION-domus-docs-refactor-2026-04-04

2026-04-04: Hub Audit Methodology (16-File Sweep)

Problem: Hub repo had accumulated stale references over months — supplemental-ui/ (deleted), pfSense (replaced), wrong component names, incomplete repo lists

Context: domus-docs full audit after growing from 5 to 15 components

The Fix:

# Systematic audit checklist for Antora hub repos:

# 1. Stale directory references
grep -rn 'supplemental-ui' . --include='*.adoc' --include='*.d2' --include='*.yml'

# 2. Renamed infrastructure
grep -rn 'pfsense\|pfSense' docs/ --include='*.adoc'

# 3. Wrong component names (verify against actual antora.yml)
for repo in ~/atelier/_bibliotheca/domus-*/; do
  awk 'NR==1 && /^name:/ {print FILENAME, $2}' "$repo"docs/asciidoc/antora.yml 2>/dev/null
done

# 4. Component count vs playbook sources
awk '/- url:/ && !/^[[:space:]]*#/' antora-playbook.yml | wc -l

# 5. Cross-repo impact (check captures, other repos that reference hub)
grep -rn '16 spoke\|16 component' ~/atelier/_bibliotheca/domus-captures/docs/

Rule: Schedule hub audits quarterly. Spoke repos evolve independently — the hub drifts silently. Check: playbook source counts, attribute accuracy, D2 diagrams, README, deployment docs, and cross-repo references in domus-captures.

Session: SESSION-domus-docs-refactor-2026-04-04