CR-2026-02-26 - Antora Build Error Fixes

Change Request Summary

Field Value

CR ID

CR-2026-02-26-002

Status

Completed

Priority

P2

Requester

evanusmodestus

Date

2026-02-26

Description

Fix Antora build errors discovered during domus-docs hub refresh:

  1. Missing xref targets (pages referenced but don’t exist)

  2. Table formatting issues (unescaped pipe characters)

Diagnostic Commands

Find Specific Lines in Files

# Print lines N through M with line numbers
awk 'NR>=920 && NR<=935 {print NR": "$0}' file.adoc

# Example: Check table structure around error line
awk 'NR>=950 && NR<=970 {print NR": "$0}' \
  /home/evanusmodestus/atelier/_bibliotheca/domus-infra-ops/docs/asciidoc/modules/ROOT/pages/runbooks/kvm-02-deployment.adoc

Find Unescaped Pipes in Tables

# Find backtick-wrapped content containing pipes
grep -n '`[^`]*|[^`]*`' file.adoc

# Example: Check sed.adoc for pipe issues
grep -n '`[^`]*|[^`]*`' \
  /home/evanusmodestus/atelier/_bibliotheca/domus-linux-ops/docs/asciidoc/modules/ROOT/pages/commands/tools/cli-mastery/sed.adoc

Find Broken xrefs Across Repos

# Search for xref pattern in repo
grep -rn 'xref:[a-z-/]*\.adoc' docs/ | head -20

# Verify specific xref target exists
ls -la docs/asciidoc/modules/ROOT/pages/runbooks/credential-rotation-checklist.adoc

Errors Fixed

1. CR-2026-02-26-claude-settings-credential-exposure.adoc

Error:

target of xref not found: runbooks/credential-rotation-checklist.adoc

Root cause: Referenced a runbook that doesn’t exist yet.

Fix: Changed xref to plain text (pending runbook):

- * xref:runbooks/credential-rotation-checklist.adoc[Credential Rotation Checklist] (stub)
+ * Credential Rotation Checklist (pending - create runbook)

2. kvm-02-deployment.adoc (Line 925)

Error:

dropping cells from incomplete row detected end of table

Root cause: Unescaped pipe | inside backticks interpreted as table cell delimiter.

Problematic code:

| `virsh dumpxml <vm> | grep -A2 '<interface'`

Fix: Escape the pipe with backslash:

| `virsh dumpxml <vm> \| grep -A2 '<interface'`

3. kvm-02-deployment.adoc (Line 954)

Error:

dropping cells from incomplete row detected end of table

Root cause: Same issue - unescaped pipe in dmesg | grep.

Fix:

- | `dmesg | grep -i iommu`
+ | `dmesg \| grep -i iommu`

4. sed.adoc (Line 550)

Error:

dropping cells from incomplete row detected end of table

Root cause: sed alternate delimiter s|/old|/new|g has unescaped pipes.

Fix:

- | `sed 's|/old|/new|g'`
+ | `sed 's\|/old\|/new\|g'`

5. git-forge-clis.adoc (Line 433)

Error:

target of xref not found: runbooks/git-repo-operations.adoc

Root cause: linux-ops doesn’t have a runbooks directory - that’s an infra-ops pattern.

Fix: Changed xref to plain text:

- * xref:runbooks/git-repo-operations.adoc[Git Repository Operations]
+ * Git Repository Operations (infra-ops) - Multi-forge workflow runbook

Key Learnings

Issue Prevention

Pipe in backticks inside table

Always escape pipes in table cells: command | grep

xref to non-existent pages

Run make before committing to catch broken xrefs

Cross-component xref in spoke repos

Use plain text instead - xrefs only work in aggregator

Verification

# Rebuild to verify no errors
cd /home/evanusmodestus/atelier/_bibliotheca/domus-docs
npx antora antora-playbook-local.yml 2>&1 | grep -E "ERROR"

# Expected: No output (clean build)

Files Modified

Repository File

domus-infra-ops

pages/changes/CR-2026-02-26-claude-settings-credential-exposure.adoc

domus-infra-ops

pages/runbooks/kvm-02-deployment.adoc

domus-linux-ops

pages/commands/tools/cli-mastery/sed.adoc

domus-linux-ops

pages/commands/tools/jq/git-forge-clis.adoc

Approval

Role Name Date

Requester

evanusmodestus

2026-02-26

Approver

evanusmodestus

2026-02-26