Appendix: File Tree Reference
Appendix: Complete File Tree
Hub Repository (team-docs)
team-docs/ # The hub — orchestrates everything
├── antora-playbook.yml # THE PLAYBOOK
│ ├── site: title, url, start_page
│ ├── content.sources: hub + all spokes
│ │ ├── hub: url=. start_path=docs
│ │ └── spokes: url=<git> start_path=docs/asciidoc
│ ├── ui.bundle: URL to UI bundle zip
│ ├── antora.extensions: lunr-extension (search)
│ ├── asciidoc.attributes: global attrs (company, domain, versions)
│ ├── asciidoc.extensions: tabs, kroki (optional)
│ ├── output: ./build/site
│ └── runtime: fetch=true
├── Makefile # make, make serve, make check, make clean
├── build.sh # CI/CD build (credential injection, UI fetch)
├── .gitignore # build/, .cache/, node_modules/
├── .github/workflows/docs.yml # GitHub Actions (optional)
└── docs/ # Hub component (start_path=docs)
├── antora.yml # name=home, global attrs (14 entries)
└── modules/ROOT/
├── nav.adoc # Cross-component links to all spokes
└── pages/
└── index.adoc # Landing page — component table, quick linksTechnical Spoke (docs/asciidoc pattern)
Used for: infrastructure, NAC, automation, security — any spoke with deep technical content.
infra-docs/ # Spoke: Infrastructure Operations
├── docs/
│ └── asciidoc/ # ← start_path in playbook
│ ├── antora.yml # name=infra-ops, 80-200+ attributes
│ │ ├── name: infra-ops # Component ID for xrefs
│ │ ├── title: Infrastructure Operations
│ │ ├── nav: modules/ROOT/nav.adoc
│ │ └── asciidoc.attributes:
│ │ ├── nav_order, category # Sidebar ordering
│ │ ├── Hostnames (20-50 entries) # sw-core-01-hostname, ise-01-hostname
│ │ ├── IP addresses (20-50 entries) # sw-core-01-ip, ise-01-ip
│ │ ├── VLANs & subnets (10-20) # vlan-data, subnet-data, gateway-data
│ │ ├── Ports (10-15) # port-radius-auth, port-tacacs
│ │ ├── Filesystem paths (5-10) # cert-dir, backup-dir
│ │ └── Personnel (3-5) # person-lead, team-name
│ └── modules/ROOT/
│ ├── nav.adoc # 50-100 lines, grouped by section
│ ├── pages/ # Every file gets its own URL
│ │ ├── index.adoc # Component landing page
│ │ ├── runbooks/ # Operational procedures
│ │ │ ├── switch-upgrade.adoc
│ │ │ ├── firewall-change.adoc
│ │ │ └── circuit-activation.adoc
│ │ ├── architecture/ # Design documents
│ │ │ ├── network-topology.adoc
│ │ │ ├── vlan-design.adoc
│ │ │ └── ha-design.adoc
│ │ ├── reference/ # Tables, inventories
│ │ │ ├── vlan-table.adoc
│ │ │ ├── ip-allocation.adoc
│ │ │ └── port-standards.adoc
│ │ ├── validated/ # Validated designs (tested configs)
│ │ │ ├── network/
│ │ │ ├── identity/
│ │ │ └── pki/
│ │ ├── incidents/ # Incident reports
│ │ ├── changes/ # Change records
│ │ └── projects/ # Project documentation
│ ├── partials/ # Reusable content (no URLs)
│ │ ├── common/ # Shared across pages
│ │ │ ├── change-control-note.adoc
│ │ │ └── pre-check-template.adoc
│ │ ├── runbooks/ # Runbook-specific partials
│ │ │ ├── backup-procedures.adoc
│ │ │ └── verification-steps.adoc
│ │ └── nav/ # Nav partials (when >50 pages)
│ │ ├── runbooks.adoc
│ │ ├── architecture.adoc
│ │ └── reference.adoc
│ ├── examples/ # Code, scripts, configs (included in pages)
│ │ ├── scripts/
│ │ │ ├── backup-switch.sh
│ │ │ └── vlan-audit.py
│ │ ├── configs/
│ │ │ ├── radius-template.conf
│ │ │ └── tacacs-template.conf
│ │ └── diagrams/
│ │ └── topology.d2
│ ├── images/ # Screenshots, diagrams (rendered)
│ │ └── diagrams/
│ │ └── network-topology.png
│ ├── attachments/ # Downloadable files
│ └── _drafts/ # Work in progress (not published)
├── scripts/ # Non-doc operational scripts
├── README.adoc
└── .gitignoreNarrative Spoke (docs pattern — simplified)
Used for: worklogs, case studies, meeting notes — content that’s narrative-first, not deeply modular.
chronicles/ # Spoke: Work Chronicles
├── docs/ # ← start_path (no asciidoc subdirectory)
│ ├── antora.yml # name=chronicles, noindex for large spokes
│ └── modules/ROOT/
│ ├── nav.adoc # 30 lines, include-driven
│ ├── pages/
│ │ ├── index.adoc
│ │ ├── 2026/ # Organized by time
│ │ │ ├── 04/
│ │ │ │ ├── WRKLOG-2026-04-07.adoc
│ │ │ │ └── index.adoc
│ │ ├── case-studies/
│ │ │ ├── incidents/
│ │ │ └── changes/
│ │ └── sessions/
│ ├── partials/
│ │ ├── nav/ # Modular nav (7+ files)
│ │ │ ├── case-studies.adoc
│ │ │ ├── chronicle-2026.adoc
│ │ │ └── training-sessions.adoc
│ │ └── worklog/ # Worklog includes
│ └── examples/
└── .gitignoreMulti-Spoke System (Production Layout)
workspace/
├── team-docs/ # Hub — playbook + landing pages
│ ├── antora-playbook.yml # References all spokes
│ ├── Makefile
│ └── docs/ # start_path=docs
│
├── infra-docs/ # Spoke: Infrastructure (docs/asciidoc)
│ └── docs/asciidoc/ # start_path=docs/asciidoc
│ ├── antora.yml # name: infra-ops, 200+ attributes
│ └── modules/ROOT/ # Runbooks, architecture, reference
│
├── nac-docs/ # Spoke: NAC/ISE (docs/asciidoc)
│ └── docs/asciidoc/
│ ├── antora.yml # name: nac-ops, 150+ attributes
│ └── modules/ROOT/ # 802.1X, profiling, policy, dACLs
│
├── automation-docs/ # Spoke: Automation (docs/asciidoc)
│ └── docs/asciidoc/
│ ├── antora.yml # name: automation
│ └── modules/ROOT/ # Scripts, playbooks, API docs
│
├── security-docs/ # Spoke: Security (docs/asciidoc)
│ └── docs/asciidoc/
│ ├── antora.yml # name: security-ops
│ └── modules/ROOT/ # Firewall, VPN, certificates
│
└── chronicles/ # Spoke: Work Chronicles (docs)
└── docs/ # start_path=docs (simplified)
├── antora.yml # name: chronicles, noindex: ''
└── modules/ROOT/ # Worklogs, incidents, sessionsstart_path Decision Guide
| Pattern | start_path | When to Use |
|---|---|---|
|
Technical spokes |
Deep module structure with partials, examples, validated designs. Room for non-Antora content in |
|
Hub + narrative spokes |
Simpler structure. Worklogs, case studies, meeting notes. No need for asciidoc subdirectory. |