Phase 08: Multi-Spoke Expansion

Phase 8: Multi-Spoke Expansion

Once the first spoke works, add more. Each spoke is an independent repo with its own antora.yml.

Adding a Second Spoke

Create the repo following the Phase 2 pattern, then add to the playbook:

content:
  sources:
    - url: .
      branches: HEAD
      start_path: docs

    # Infrastructure Operations
    - url: https://github.com/your-org/infra-docs
      branches: main
      start_path: docs

    # NAC/ISE Operations (NEW)
    - url: https://github.com/your-org/nac-docs
      branches: main
      start_path: docs

Suggested Spoke Layout for Network Engineering

Spoke Component Name Content

infra-docs

infra-ops

Runbooks, architecture, hardware inventory, VLANs

nac-docs

nac-ops

802.1X, ISE policy, profiling, dACLs, RADIUS

automation-docs

automation

Scripts, Python tools, Ansible playbooks, API docs

security-docs

security-ops

Firewall policies, VPN, certificates, compliance

onboarding-docs

onboarding

New hire guides, access requests, tool setup

Cross-Component References

Link from one spoke to another using double-colon syntax:

// From infra-docs, link to nac-docs:
See xref:nac-ops::policies/dot1x.adoc[802.1X Policy Configuration].

// From nac-docs, link to infra-docs:
Refer to xref:infra-ops::reference/vlan-table.adoc[VLAN Reference Table].

Shared Attributes Across Spokes

Attributes defined in antora-playbook.yml under asciidoc.attributes are available to ALL spokes. Use this for truly global values:

# In antora-playbook.yml
asciidoc:
  attributes:
    company-name: CHLA
    team-email: neteng@example.com
    domain: corp.example.com

Spoke-specific attributes stay in each spoke’s antora.yml. If the same attribute is defined in both, the spoke’s value wins.

Navigation Best Practices

Small site (1-3 spokes): Flat nav.adoc with direct xrefs.

Medium site (4-8 spokes): Group by section in nav.adoc.

Large site (9+ spokes): Split navigation into partials:

// nav.adoc
include::partial$nav/runbooks.adoc[]
include::partial$nav/architecture.adoc[]
include::partial$nav/reference.adoc[]

Each partial manages its own section of the nav tree. This is the pattern used in the domus-captures system (7 nav partials, 1,000+ lines).