STD-015: Antora Attribute Standards

The antora.yml file is the single source of truth for all mutable values across the captures component. Every IP address, hostname, port, path, status indicator, and statistical counter is defined here as an attribute. Hardcoded literals in .adoc files are a defect. This standard governs how attributes are structured, organized, and maintained.

Principles

  1. Attributes over literals. No mutable value is ever hardcoded in a document. IPs, hostnames, ports, MACs, VLANs, paths, policy names, statistics, dates, and status indicators are ALL expressed as {attribute-name}. This is not a preference — it is a build-quality invariant.

  2. Organized by section with comment headers. Attributes are grouped into logical sections, each separated by a comment banner (# ===…​). This makes visual scanning and maintenance tractable as the attribute count grows.

  3. Maintenance cadence is defined. Each section carries inline comments specifying WHEN and HOW to update. Stale attributes (wrong month, outdated stats) erode trust in the entire system.

  4. attribute-missing: warn catches typos. This setting is non-negotiable. When an {attribute} reference has no definition, the Antora build emits a warning instead of silently rendering the literal {attribute-name}. This is the primary defense against attribute typos.

Section Organization

The antora.yml attributes block is organized into the following sections, in order:

Section Purpose Example Attributes

AsciiDoc Features

Rendering behavior, syntax highlighting, section linking, error handling

icons, experimental, source-highlighter, attribute-missing, page-toclevels

Custom Admonitions

Emoji-prefixed captions for admonition blocks

tip-caption, note-caption, warning-caption, caution-caption, important-caption

Document Types

Reusable labels for document type identification

type-wrklog, type-mtg, type-doc, type-plan, type-ref, type-setup

Status Indicators

Icon-based status labels for tables and inline use

status-active, status-complete, status-archived, status-planned, status-done

Maintenance: Current Period

Calendar attributes for the current month

current-year, current-month, current-month-num, current-month-path, months-active

Quarterly Statistics

Worklog and case study counts per quarter

stats-2026-q1-worklogs, stats-2026-q1-cases, stats-2026-q1-rcas

Case Study Statistics

Aggregate counts across all case study types

stats-cs-tac, stats-cs-incidents, stats-cs-changes, stats-cs-rca, stats-cs-deployments

Monthly Focus Areas

Comma-separated initiatives per month

focus-2026-01, focus-2026-02, focus-2026-03, focus-2026-04

Author Information

Contact details and identity

author, email, person-evan

Skill Levels

Progression tracking across tools and languages

level-regex, level-cli, level-awk, level-vim, level-python, level-rust

Review Cycles

Dates for audits and review cadence

last-full-review, next-quarterly-review, carryover-audit-frequency

Carryover Origin Dates

Start dates for age-in-days calculations

origin-k3s-nat, origin-monad, origin-strongline

Personal Peripherals

Bluetooth MACs and device names

bt-kinesis-mac, bt-buds-mac

Infrastructure

IPs, hostnames, ports for all lab infrastructure

domain, ise-ip, vault-ip, vyos-01-ip, ad-dc-ip, cert-dir

Maintenance Cadence

What When Action

Current Period

First day of each month

Update current-month, current-month-num, current-month-path, extend months-active range

Monthly Focus Areas

First day of each month

Add focus-YYYY-MM: line for the new month

Quarterly Statistics

Weekly, or when adding case studies

Update stats-YYYY-QN-* counts

Case Study Statistics

On event (new TAC, incident, change, RCA, deployment)

Increment the relevant stats-cs-* counter, update stats-cs-updated date

Skill Levels

Monthly or on significant progress

Adjust level-* attributes (Beginner / Intermediate / Advanced / Expert)

Review Cycles

After each review session

Update last-full-review, next-quarterly-review

Author Information

On change only

Update author, email, person-evan

Infrastructure

On change only

Update IPs, hostnames, ports. Must match domus-infra-ops/antora.yml (source of truth)

Carryover Origin Dates

On event (new long-running item)

Add origin-<slug>: 'YYYY-MM-DD'

Adding New Attributes

When adding a new attribute:

  1. Identify the correct section by consulting the section table above.

  2. Place the attribute within that section, maintaining alphabetical order within subsections where practical.

  3. Add an inline comment if the attribute’s purpose is not self-evident.

  4. If no existing section fits, create a new section with a comment banner following the established format:

        # =========================================================================
    # SECTION NAME
    # UPDATE: [cadence description]
    # =========================================================================

Requirements

  1. Every mutable value in any .adoc file MUST be an attribute defined in antora.yml.

  2. New attributes MUST be added to the correct section, respecting comment headers and grouping.

  3. Monthly maintenance MUST be performed on the first day of each month: current period, focus areas, and statistics.

  4. Case study statistics MUST be updated when adding any case study (TAC, incident, change, RCA, deployment).

  5. attribute-missing MUST be set to warn — never skip or drop.

  6. Infrastructure attributes MUST remain consistent with domus-infra-ops/antora.yml as the upstream source of truth.

  7. Deprecated attributes (e.g., pfSense) MUST be retained with a # DEPRECATED comment and date for historical document references.

  8. Code blocks referencing attributes MUST include subs=attributes+.

Compliance

Check Method Pass Criterion

No hardcoded IPs

grep -rP '\b\d+\.\d+\.\d+\.\d+\b' pages/ | grep -v '{' | grep -v '//'

Zero matches

No hardcoded hostnames

grep -rP '\w+\.inside\.domusdigitalis\.dev' pages/ | grep -v '{' | grep -v '//'

Zero matches

Maintenance dates current

grep 'current-month:' docs/antora.yml

Matches actual calendar month

attribute-missing is warn

grep 'attribute-missing' docs/antora.yml

Value is warn

Stats updated date recent

grep 'stats-cs-updated' docs/antora.yml

Within 30 days of current date

Sections have comment headers

Visual inspection of antora.yml

Every attribute group has a # === banner

No orphaned attributes

grep -oP '\{[\w-]+\}' pages/*/.adoc | sort -u cross-referenced against antora.yml

Every referenced attribute has a definition

Related