Phase 06: Build and Local Preview

Phase 6: Build and Local Preview

Basic Build

cd team-docs
npx antora antora-playbook.yml

Output goes to build/site/. Open build/site/index.html in a browser.

Local Development Server

npx antora antora-playbook.yml && npx http-server build/site -p 8080
# Open http://localhost:8080

Or use the Makefile:

make serve

Build with Warnings

Check for broken xrefs, missing includes, and attribute errors:

npx antora antora-playbook.yml 2>&1 | grep -E "WARN|ERROR"

Common warnings and fixes:

Warning Fix

xref target not found

File doesn’t exist or path is wrong. Check pages/ directory.

include target not found

Partial or example file doesn’t exist. Check partials/ or examples/.

source= globbing error: found no match

A source = line in config references a file that doesn’t exist.

skipping reference to missing attribute

Attribute used in a page but not defined in antora.yml.

Makefile (Extended)

.PHONY: all serve clean check

all:
	npx antora antora-playbook.yml

serve: all
	npx http-server build/site -p 8080

clean:
	rm -rf build .cache

check:
	npx antora antora-playbook.yml 2>&1 | grep -E "WARN|ERROR" || echo "Build clean"

Kroki Diagrams (Optional)

Add diagram support (D2, PlantUML, Mermaid) via Kroki:

# In antora-playbook.yml
asciidoc:
  attributes:
    kroki-server-url: https://kroki.io
    kroki-fetch-diagram: true
  extensions:
    - "asciidoctor-kroki"

Then in any page:

[d2]
....
switch -> firewall: trunk
firewall -> internet: NAT
....