Phase 04: Attributes System

Phase 4: Attributes System

Attributes are Antora’s variable system. Define a value once in antora.yml, reference it everywhere with {attribute-name}. When a value changes (IP address, hostname, VLAN), update one file — every document updates automatically.

Define Attributes in antora.yml

asciidoc:
  attributes:
    # Domain
    domain: corp.example.com

    # Network devices — hostnames
    sw-core-01-hostname: sw-core-01.corp.example.com
    sw-core-02-hostname: sw-core-02.corp.example.com

    # Network devices — IPs
    sw-core-01-ip: 10.1.1.1
    sw-core-02-ip: 10.1.1.2
    fw-01-ip: 10.1.1.10
    wlc-01-ip: 10.1.1.20

    # Servers
    ise-01-ip: 10.1.10.20
    ise-02-ip: 10.1.10.21
    dc-01-ip: 10.1.10.50
    nps-01-ip: 10.1.10.60

    # VLANs
    vlan-mgmt: 10
    vlan-data: 20
    vlan-voice: 30
    vlan-iot: 40
    vlan-guest: 50

    # Ports
    port-radius: 1812
    port-radius-acct: 1813
    port-tacacs: 49
    port-snmp: 161
    port-syslog: 514
    port-ntp: 123

    # Paths
    cert-dir: /etc/ssl/certs
    key-dir: /etc/ssl/private
    backup-dir: /opt/backups

    # People / roles
    person-lead: NetworkLead
    team-name: Network Engineering

Use Attributes in Prose

In running text, use attributes bare — no inline code wrapping:

// WRONG — inline code with mutable literal
Connect to `10.1.1.1` for switch management.

// CORRECT — attribute in prose
Connect to {sw-core-01-ip} for switch management.

Use Attributes in Code Blocks

Add subs=attributes+ to render attribute values:

[source,bash,subs=attributes+]
----
# SSH to core switch
ssh admin@{sw-core-01-ip}

# Check RADIUS configuration
show aaa server | include {ise-01-ip}
show aaa server | include {ise-02-ip}

# Verify VLAN
show vlan brief | include {vlan-data}
----

Attribute Naming Convention

Pattern Example Use

<device>-ip

sw-core-01-ip

IP addresses

<device>-hostname

sw-core-01-hostname

FQDNs

vlan-<name>

vlan-data

VLAN IDs

port-<service>

port-radius

Protocol ports

<path>-dir

cert-dir

File system paths

person-<role>

person-lead

Team members

Pre-Write Checklist

Before using any attribute in a document:

# 1. List available attributes
grep -E "^    [a-z]" docs/antora.yml | head -50

# 2. Search for a specific attribute
grep -i "ise" docs/antora.yml

# 3. If the attribute doesn't exist, ADD IT to antora.yml first

Never assume an attribute exists. Never hardcode what an attribute should express.