Phase 01: Hub Repository

mkdir team-docs && cd team-docs
git init
mkdir -p docs/modules/ROOT/pages

# ============================================================================
# Team Documentation — Antora Playbook
# ============================================================================
# Central orchestration for all documentation components.
#
# Components:
#   - home: Landing page (this repo)
#   - infra-ops: Infrastructure operations
#   - nac-ops: NAC/ISE operations
#   (add more as you create spoke repos)
#
# Usage:
#   npx antora antora-playbook.yml
#   make
#
# Maintainer: Network Engineering
# ============================================================================

site:
  title: Network Engineering Documentation
  url: https://docs.internal.example.com  # Replace with your site URL
  start_page: home::index.adoc

content:
  sources:
    # ──────────────────────────────────────────────────────────────
    # HUB (this repo) — landing pages and cross-component nav
    # ──────────────────────────────────────────────────────────────
    - url: .
      branches: HEAD
      start_path: docs
      edit_url: false

    # ──────────────────────────────────────────────────────────────
    # SPOKE REPOS — one per documentation domain
    # start_path: docs/asciidoc for full technical spokes
    # start_path: docs for lightweight/narrative spokes
    # ──────────────────────────────────────────────────────────────

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

    # NAC/ISE Operations (uncomment when ready)
    # - url: https://github.com/your-org/nac-docs
    #   branches: main
    #   start_path: docs/asciidoc
    #   edit_url: false

    # ──────────────────────────────────────────────────────────────
    # LOCAL DEVELOPMENT — uncomment for local builds
    # ──────────────────────────────────────────────────────────────
    # - url: ../infra-docs
    #   branches: HEAD
    #   start_path: docs/asciidoc

ui:
  bundle:
    # Default Antora UI (replace with custom bundle when ready)
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true

antora:
  extensions:
    # Full-text search (optional — add @antora/lunr-extension to package.json)
    # - require: "@antora/lunr-extension"
    #   index_latest_only: true
    #   languages: [en]

asciidoc:
  attributes:
    # Suppress warnings for intentional placeholders
    attribute-missing: skip
    # Global attributes (available to ALL components)
    page-pagination: ""
    hide-uri-scheme: ""
    # Diagram server (uncomment when using Kroki)
    # kroki-server-url: https://kroki.io
    # kroki-fetch-diagram: true
  # Extensions (uncomment as needed)
  # extensions:
  #   - "@asciidoctor/tabs"
  #   - "asciidoctor-kroki"

output:
  dir: ./build/site
  clean: true

runtime:
  fetch: true
  cache_dir: .cache/antora

name: home
title: Network Engineering
version: ~
start_page: ROOT:index.adoc
nav:
  - modules/ROOT/nav.adoc
asciidoc:
  attributes:
    # Global infrastructure versions (shared across all spokes)
    company-name: CHLA
    team-name: Network Engineering
    domain: corp.example.com
    ise-version: '3.3'
    # Add versions and global constants here
    # Spokes inherit these but can override

= Network Engineering Documentation
:description: Central documentation hub — runbooks, architecture, operations
:icons: font

Documentation system for the network engineering team.

== Components

[cols="2,3,1"]
|===
| Component | Description | Pages

| xref:infra-ops::index.adoc[Infrastructure Operations]
| Runbooks, architecture, validated designs, reference tables
| TBD

| NAC/ISE Operations _(coming soon)_
| 802.1X, profiling, policy sets, dACLs, RADIUS
| —

| Automation _(coming soon)_
| Scripts, Ansible playbooks, API documentation
| —
|===

== Quick Links

* xref:infra-ops::runbooks/index.adoc[All Runbooks]
* xref:infra-ops::reference/vlan-table.adoc[VLAN Reference]

* xref:index.adoc[Home]
* .Infrastructure
** xref:infra-ops::index.adoc[Operations Hub]
** xref:infra-ops::runbooks/index.adoc[Runbooks]
** xref:infra-ops::architecture/index.adoc[Architecture]
* .NAC & ISE
** _Coming soon_
* .Automation
** _Coming soon_

.PHONY: all serve clean check

# Build the site
all:
	npx antora antora-playbook.yml

# Build and serve locally
serve: all
	@echo "Serving at http://localhost:8080"
	npx http-server build/site -p 8080

# Check for build warnings
check:
	@npx antora antora-playbook.yml 2>&1 | grep -E "WARN|ERROR" || echo "Build clean — no warnings"

# Clean build artifacts
clean:
	rm -rf build .cache

build/
.cache/
node_modules/
package-lock.json

npx antora antora-playbook.yml
make check
# Open build/site/index.html

team-docs/
├── antora-playbook.yml         # THE PLAYBOOK — heart of the system
├── Makefile                    # make, make serve, make check, make clean
├── .gitignore
└── docs/
    ├── antora.yml              # Hub component: name=home, global attributes
    └── modules/ROOT/
        ├── nav.adoc            # Cross-component navigation
        └── pages/
            └── index.adoc      # Landing page with component table