Team-Based Multi-Module Template

1. Overview

This template provides a ready-to-use structure for projects where multiple teams contribute to a single documentation repository. Each team owns their module while sharing common attributes and cross-linking seamlessly.

When to use this pattern:

Single project with multiple teams (Network, Security, Linux, Cloud)
Shared infrastructure requiring unified documentation
Enterprise deployments where teams need independence but unified output

2. Architecture

project-docs/
├── Makefile
├── README.adoc
├── docs/asciidoc/
│   ├── antora.yml                    # Component descriptor (shared attributes)
│   ├── antora-playbook.yml           # Local build playbook
│   └── modules/
│       ├── ROOT/                     # Core documentation
│       │   ├── nav.adoc
│       │   └── pages/
│       │       ├── index.adoc        # Project landing page
│       │       ├── architecture.adoc # Overall architecture
│       │       └── glossary.adoc     # Shared terminology
│       │
│       ├── network/                  # Network team module
│       │   ├── nav.adoc
│       │   └── pages/
│       │       ├── index.adoc
│       │       ├── topology.adoc
│       │       └── firewall.adoc
│       │
│       ├── security/                 # Security team module
│       │   ├── nav.adoc
│       │   └── pages/
│       │       ├── index.adoc
│       │       ├── ise-policy.adoc
│       │       └── certificates.adoc
│       │
│       └── linux/                    # Linux team module
│           ├── nav.adoc
│           └── pages/
│               ├── index.adoc
│               ├── 802.1x-client.adoc
│               └── troubleshooting.adoc

3. File Templates

3.1. antora.yml (Component Descriptor)

name: project-docs
title: Enterprise Project Documentation
version: '2026'
start_page: ROOT:index.adoc

# Include all team module navigations
nav:
  - modules/ROOT/nav.adoc
  - modules/network/nav.adoc
  - modules/security/nav.adoc
  - modules/linux/nav.adoc

asciidoc:
  attributes:
    # ========================================================================
    # PROJECT METADATA
    # ========================================================================
    project-name: Enterprise Deployment
    project-code: PRJ-ENT-001
    project-status: Active

    # ========================================================================
    # TEAM OWNERSHIP
    # ========================================================================
    team-network: Network Infrastructure Team
    team-security: Security Operations Team
    team-linux: Linux Engineering Team
    team-lead-network: Victor
    team-lead-security: Ben
    team-lead-linux: Evan

    # ========================================================================
    # SHARED INFRASTRUCTURE
    # ========================================================================
    # Domain
    domain: corp.example.com
    domain-internal: inside.corp.example.com

    # Core Services
    dns-primary: 10.0.1.1
    dns-secondary: 10.0.1.2
    ntp-server: ntp.corp.example.com

    # ISE Cluster
    ise-pan-ip: 10.0.1.20
    ise-psn-ip: 10.0.1.21
    ise-hostname: ise-01.corp.example.com

    # Network Infrastructure
    firewall-ip: 10.0.1.1
    switch-core-ip: 10.0.1.10
    wlc-ip: 10.0.1.40

    # ========================================================================
    # VLAN CONFIGURATION (shared across teams)
    # ========================================================================
    vlan-mgmt: 100
    vlan-data: 10
    vlan-voice: 20
    vlan-guest: 30
    vlan-iot: 40
    vlan-quarantine: 999

    # ========================================================================
    # PKI CONFIGURATION
    # ========================================================================
    ca-root: CORP-ROOT-CA
    ca-issuing: CORP-ISSUING-CA
    cert-dir: /etc/ssl/certs
    key-dir: /etc/ssl/private

    # ========================================================================
    # POLICY NAMES (ISE)
    # ========================================================================
    policy-set-wired: Wired_802.1X
    policy-set-wifi: Wireless_802.1X
    dacl-full-access: DACL_Full_Access
    dacl-restricted: DACL_Restricted
    dacl-quarantine: DACL_Quarantine

    # ========================================================================
    # TEAM-SPECIFIC ATTRIBUTES
    # ========================================================================
    # Network team
    network-diagram-tool: Visio
    network-automation: Terraform

    # Security team
    siem-platform: Splunk
    edr-agent: CrowdStrike

    # Linux team
    linux-distro: RHEL 9
    config-mgmt: Ansible

3.2. ROOT Module (Core Documentation)

3.2.1. modules/ROOT/nav.adoc

* xref:index.adoc[Project Overview]
* xref:architecture.adoc[Architecture]
* xref:glossary.adoc[Glossary]
* xref:contacts.adoc[Team Contacts]

3.2.2. modules/ROOT/pages/index.adoc

= {project-name}
:description: Central documentation hub for {project-name}

== Overview

Welcome to the {project-name} documentation. This site consolidates documentation from all project teams.

== Team Modules

[cols="1,2,1"]
|===
|Team |Documentation |Lead

|Network
|xref:network:index.adoc[Network Documentation]
|{team-lead-network}

|Security
|xref:security:index.adoc[Security Documentation]
|{team-lead-security}

|Linux
|xref:linux:index.adoc[Linux Documentation]
|{team-lead-linux}
|===

== Quick Links

* xref:architecture.adoc[System Architecture]
* xref:network:topology.adoc[Network Topology]
* xref:security:ise-policy.adoc[ISE Policy Configuration]
* xref:linux:802.1x-client.adoc[Linux 802.1X Setup]

3.3. Team Module Template

3.3.1. modules/[team]/nav.adoc

.Network Team
* xref:index.adoc[Overview]
* xref:topology.adoc[Network Topology]
* xref:firewall.adoc[Firewall Configuration]
* xref:vlans.adoc[VLAN Architecture]

3.3.2. modules/[team]/pages/index.adoc

= Network Team Documentation
:description: Network infrastructure documentation for {project-name}

== Overview

This module contains documentation maintained by the {team-network}.

Team Lead:: {team-lead-network}
Last Updated:: {revdate}

== Contents

* xref:topology.adoc[Network Topology] - Physical and logical network design
* xref:firewall.adoc[Firewall Configuration] - {firewall-ip} rule sets
* xref:vlans.adoc[VLAN Architecture] - Segmentation design

== Related Documentation

* xref:ROOT:architecture.adoc[Project Architecture]
* xref:security:ise-policy.adoc[ISE Policy] (Security team)
* xref:linux:802.1x-client.adoc[Linux Client] (Linux team)

4. Cross-Module Linking

4.1. Syntax Reference

Link Type Syntax

Link Type	Syntax
Same module	`xref:page.adoc[Text]`
Different module (same component)	`xref:module:page.adoc[Text]`
ROOT module	`xref:ROOT:page.adoc[Text]`

Same module

xref:page.adoc[Text]

Different module (same component)

xref:module:page.adoc[Text]

ROOT module

xref:ROOT:page.adoc[Text]

4.2. Examples

// From network module, link to security module
For authentication policy, see xref:security:ise-policy.adoc[ISE Policy Configuration].

// From any module, link to ROOT
See the xref:ROOT:architecture.adoc[overall architecture].

// From any module, link to network topology
The network design is documented in xref:network:topology.adoc[Network Topology].

// Link with section anchor
See xref:security:ise-policy.adoc#dacl-config[dACL Configuration].

5. Shared Attributes Usage

All modules inherit attributes from antora.yml:

// In any module's page:
The ISE primary admin node is at `{ise-pan-ip}`.

Configure the client to use VLAN `{vlan-data}`.

Certificates are issued by `{ca-issuing}`.

This documentation is maintained by {team-network}.

6. Build Configuration

6.1. Makefile

# Project Documentation Makefile
PLAYBOOK := docs/asciidoc/antora-playbook.yml
BUILD_DIR := docs/asciidoc/build/site

.PHONY: all site serve clean

all: site

site:
	@echo "Building documentation..."
	npx antora $(PLAYBOOK)
	@echo "Site built: $(BUILD_DIR)/"

serve: site
	@echo "Serving at http://localhost:8000"
	cd $(BUILD_DIR) && python3 -m http.server 8000

clean:
	rm -rf $(BUILD_DIR) .cache

# Validate all xrefs resolve
validate:
	npx antora --log-level=warn $(PLAYBOOK) 2>&1 | grep -i "xref"

6.2. antora-playbook.yml

site:
  title: Enterprise Project Documentation
  start_page: project-docs::index.adoc

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

ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true

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

8. Adding a New Team Module

Create module directory:

mkdir -p docs/asciidoc/modules/newteam/pages

Create nav.adoc:

cat > docs/asciidoc/modules/newteam/nav.adoc << 'EOF'
.New Team
* xref:index.adoc[Overview]
EOF

Create index page:

cat > docs/asciidoc/modules/newteam/pages/index.adoc << 'EOF'
= New Team Documentation
:description: Documentation for the new team

== Overview

Content here.
EOF

Add to antora.yml:

nav:
  - modules/ROOT/nav.adoc
  - modules/network/nav.adoc
  - modules/security/nav.adoc
  - modules/linux/nav.adoc
  - modules/newteam/nav.adoc      # Add this line

Add team attributes to antora.yml:

team-newteam: New Team Name
team-lead-newteam: Team Lead Name

Rebuild: make site

9. Integration with Hub-Spoke

If this project should also be aggregated into a larger documentation hub:

Ensure antora.yml has a unique component name

Add to hub’s antora-playbook.yml:

content:
  sources:
    # Existing components...

    - url: https://github.com/org/project-docs
      branches: main
      start_path: docs/asciidoc

Cross-component links from hub use:

xref:project-docs::network:topology.adoc[Project Network Topology]