AsciiDoc Conditional Attributes

AsciiDoc Conditional Preprocessor — Reference

AsciiDoc’s preprocessor runs before Asciidoctor parses content and before Kroki renders diagram blocks. This means attributes resolve in the right order:

antora-playbook.yml / CLI flag
        ↓
partials/attributes.adoc  (ifdef selects the right values)
        ↓
page content              ({attribute} substitution)
        ↓
Kroki                     (sees resolved literals, not attribute tokens)
        ↓
SVG output

This makes partials/attributes.adoc the single source of truth for both prose and diagrams.

Directive Reference

ifdef — block executes if attribute IS defined

ifndef — block executes if attribute is NOT defined

This content appears when my-flag is absent.

ifdef inline (single line, no endif needed)

Multiple flags — OR logic (comma = OR, plus = AND)

// Either flag triggers this block

// Both flags must be set

ifeval — value comparison

ifeval compares strings or integers. Wrap attribute references in "" for string comparison. Operators: == != < > <= >=.

Setting the Flag

Standalone Asciidoctor (CLI)

# Set a flag (value is empty string — presence is what matters)
asciidoctor -a env-d000 doc.adoc
asciidoctor -a env-d001 doc.adoc

# Set a flag AND a value
asciidoctor -a env-d001 -a ise-version=3.3 doc.adoc

# Multiple flags
asciidoctor -a env-d001 -a debug doc.adoc

Antora Playbook (antora-playbook.yml) — site-wide

asciidoc:
  attributes:
    env-d001: ''          # presence flag — empty string = defined
    ise-version: '3.3'
    env-production: ''

Antora Component (antora.yml) — per-component override

asciidoc:
  attributes:
    env-d000: ''
    ise-version: '3.5'
    env-production: '@'   # @ = soft-set, playbook can override
In Antora, a hard-set attribute (no @) in the playbook wins over a component antora.yml. Suffix a value with @ to make it overridable downstream.

Master Attributes Partial Pattern

This is the canonical pattern for partials/attributes.adoc. Set exactly one environment flag at build time — never hardcode it here.

// partials/attributes.adoc
// Single source of truth for all environment-sensitive values.
// DO NOT set env-* flags here — set them in antora-playbook.yml or CLI.
//
// Build targets:
//   env-d001   → CHLA production
//   env-d000  → Domus Digitalis homelab
//   (neither)  → safe fallback defaults

// ============================================================
// CHLA Production
// ============================================================

// ============================================================
// Domus Digitalis Homelab
// ============================================================

// ============================================================
// Fallback — safe defaults if no environment flag is set
// ============================================================
:ise-hostname:        ise.example.internal
:ise-version:         0.0
:ise-patch:           0
:domain:              example.internal
:vault-url:           https://vault.example.internal
:vault-tls-verify:    false
:ntp-server:          ntp.example.internal
:dns-server:          dns.example.internal
:mgmt-vlan:           100
:environment-label:   UNDEFINED — set env-d001 or env-d000

Using Attributes in Prose

// ========================================================================
// SHARED ATTRIBUTES -- Home & Personal
// ========================================================================
// Source of truth for personal identity, home infrastructure, and
// document defaults used across daily worklogs and captures.
//
// Usage:
//   include::partial$attributes.adoc[]
//
// For work-specific attributes (CHLA), also include:
//   include::partial$attributes-work.adoc[]
//
// For HTML status styling, also include:
//   include::partial$attributes-styles.adoc[]
//
// Per-document attributes (revdate, document-id, capture-date,
// focus-areas, etc.) remain in each file's header.
// ========================================================================

// ========================================================================
// DOCUMENT DEFAULTS
// ========================================================================
:id: UNSET
:document-id: {id}

// ========================================================================
// AUTHOR & IDENTITY
// ========================================================================
:author-name: Evan Rosado
:author-email-home: evan.rosado@domusdigitalis.dev
:author-email-work: erosado@chla.usc.edu
:author-email-personal: evan.rosado@outlook.com

// ========================================================================
// HOME ENTERPRISE DOMAINS
// ========================================================================
:home-domain: domusdigitalis.dev
:home-domain-internal: inside.domusdigitalis.dev
:home-domain-guest: guest.domusdigitalis.dev
:home-env-name: Home Enterprise ({home-domain})

// ========================================================================
// HOME ENTERPRISE INFRASTRUCTURE
// ========================================================================
// NOTE: These use `home-*` prefix to distinguish from antora.yml's
// top-level `ise-*`, `vault-*` etc. which are the canonical short names.
// antora.yml: {ise-ip}, {vault-hostname} — used in most docs
// attributes.adoc: {home-ise-01-ip}, {home-ise-pan-ip} — used when
// distinguishing cluster nodes or specifying the home lab context.
// ========================================================================

// ISE Cluster (Home)
:home-ise-version: 3.3
:home-ise-pan-ip: 10.50.1.21
:home-ise-pan-host: ise-02.inside.domusdigitalis.dev
:home-ise-01-ip: 10.50.1.20
:home-ise-01-host: ise-01.inside.domusdigitalis.dev
:home-ise-02-ip: 10.50.1.21
:home-ise-02-host: ise-02.inside.domusdigitalis.dev

// DNS (BIND)
:home-dns-primary: 10.50.1.90
:home-dns-secondary: 10.50.1.1
:home-bind-ip: 10.50.1.90
:home-bind-host: bind-01.inside.domusdigitalis.dev

// Active Directory
:home-ad-server: HOME-DC01.inside.domusdigitalis.dev
:home-ad-ca: HOME-ROOT-CA

// Network (VyOS replaced pfSense 2026-03-07)
:home-vyos-ip: 10.50.1.2
:home-vyos-host: vyos-01.inside.domusdigitalis.dev
:home-switch-ip: 10.50.1.10
:home-wlc-ip: 10.50.1.40
:home-wlc-host: wlc.inside.domusdigitalis.dev

// Storage
:nas-ip: 10.50.1.70
:nas-name: nas-01
:nas-nfs-path: /volume1/ise_backups

// ========================================================================
// PERSONAL PROJECTS
// ========================================================================
:prj-ipsk-home: PRJ-ISE-IPSK-HOME-ANTORA
:prj-home-linux: PRJ-ISE-HOME-LINUX-ANTORA
:prj-home-lab: PRJ-ISE-HOME-LINUX-ANTORA
:prj-netapi: PRJ-NETAPI-ANTORA
:prj-secrets: PRJ-SECRETS
:prj-recovery: PRJ-RECOVERY
:prj-infra-ops: PRJ-INFRA-OPS-ANTORA

// ========================================================================
// PERSONAL TOOLS
// ========================================================================
:tool-netapi: netapi (Personal ISE automation CLI)
:tool-dsec: dsec (Secrets management)
:tool-ansible: Ansible
:tool-git: Git

This document covers ISE {ise-version} (Patch {ise-patch}) in the
*{environment-label}* environment.

The primary node is `{ise-hostname}` on VLAN `{mgmt-vlan}`.
Vault PKI is available at `{vault-url}`.

Using Attributes in Kroki Diagram Blocks

Attributes resolve before Kroki renders — the diagram source Kroki receives contains only resolved literal strings.

Graphviz via Kroki

// ========================================================================
// SHARED ATTRIBUTES -- Home & Personal
// ========================================================================
// Source of truth for personal identity, home infrastructure, and
// document defaults used across daily worklogs and captures.
//
// Usage:
//   include::partial$attributes.adoc[]
//
// For work-specific attributes (CHLA), also include:
//   include::partial$attributes-work.adoc[]
//
// For HTML status styling, also include:
//   include::partial$attributes-styles.adoc[]
//
// Per-document attributes (revdate, document-id, capture-date,
// focus-areas, etc.) remain in each file's header.
// ========================================================================

// ========================================================================
// DOCUMENT DEFAULTS
// ========================================================================
:id: UNSET
:document-id: {id}

// ========================================================================
// AUTHOR & IDENTITY
// ========================================================================
:author-name: Evan Rosado
:author-email-home: evan.rosado@domusdigitalis.dev
:author-email-work: erosado@chla.usc.edu
:author-email-personal: evan.rosado@outlook.com

// ========================================================================
// HOME ENTERPRISE DOMAINS
// ========================================================================
:home-domain: domusdigitalis.dev
:home-domain-internal: inside.domusdigitalis.dev
:home-domain-guest: guest.domusdigitalis.dev
:home-env-name: Home Enterprise ({home-domain})

// ========================================================================
// HOME ENTERPRISE INFRASTRUCTURE
// ========================================================================
// NOTE: These use `home-*` prefix to distinguish from antora.yml's
// top-level `ise-*`, `vault-*` etc. which are the canonical short names.
// antora.yml: {ise-ip}, {vault-hostname} — used in most docs
// attributes.adoc: {home-ise-01-ip}, {home-ise-pan-ip} — used when
// distinguishing cluster nodes or specifying the home lab context.
// ========================================================================

// ISE Cluster (Home)
:home-ise-version: 3.3
:home-ise-pan-ip: 10.50.1.21
:home-ise-pan-host: ise-02.inside.domusdigitalis.dev
:home-ise-01-ip: 10.50.1.20
:home-ise-01-host: ise-01.inside.domusdigitalis.dev
:home-ise-02-ip: 10.50.1.21
:home-ise-02-host: ise-02.inside.domusdigitalis.dev

// DNS (BIND)
:home-dns-primary: 10.50.1.90
:home-dns-secondary: 10.50.1.1
:home-bind-ip: 10.50.1.90
:home-bind-host: bind-01.inside.domusdigitalis.dev

// Active Directory
:home-ad-server: HOME-DC01.inside.domusdigitalis.dev
:home-ad-ca: HOME-ROOT-CA

// Network (VyOS replaced pfSense 2026-03-07)
:home-vyos-ip: 10.50.1.2
:home-vyos-host: vyos-01.inside.domusdigitalis.dev
:home-switch-ip: 10.50.1.10
:home-wlc-ip: 10.50.1.40
:home-wlc-host: wlc.inside.domusdigitalis.dev

// Storage
:nas-ip: 10.50.1.70
:nas-name: nas-01
:nas-nfs-path: /volume1/ise_backups

// ========================================================================
// PERSONAL PROJECTS
// ========================================================================
:prj-ipsk-home: PRJ-ISE-IPSK-HOME-ANTORA
:prj-home-linux: PRJ-ISE-HOME-LINUX-ANTORA
:prj-home-lab: PRJ-ISE-HOME-LINUX-ANTORA
:prj-netapi: PRJ-NETAPI-ANTORA
:prj-secrets: PRJ-SECRETS
:prj-recovery: PRJ-RECOVERY
:prj-infra-ops: PRJ-INFRA-OPS-ANTORA

// ========================================================================
// PERSONAL TOOLS
// ========================================================================
:tool-netapi: netapi (Personal ISE automation CLI)
:tool-dsec: dsec (Secrets management)
:tool-ansible: Ansible
:tool-git: Git

[graphviz]
....
digraph ise_topology {
  rankdir=LR
  node [shape=rectangle fontname="monospace"]

  ise    [label="{ise-hostname}\nISE {ise-version}p{ise-patch}"]
  vault  [label="{vault-url}"]
  dns    [label="{dns-server}"]
  ntp    [label="{ntp-server}"]

  ise -> vault [label="PKI / SCEP"]
  ise -> dns   [label="DNS resolution"]
  ise -> ntp   [label="NTP sync"]
}
....

D2 via Kroki

// ========================================================================
// SHARED ATTRIBUTES -- Home & Personal
// ========================================================================
// Source of truth for personal identity, home infrastructure, and
// document defaults used across daily worklogs and captures.
//
// Usage:
//   include::partial$attributes.adoc[]
//
// For work-specific attributes (CHLA), also include:
//   include::partial$attributes-work.adoc[]
//
// For HTML status styling, also include:
//   include::partial$attributes-styles.adoc[]
//
// Per-document attributes (revdate, document-id, capture-date,
// focus-areas, etc.) remain in each file's header.
// ========================================================================

// ========================================================================
// DOCUMENT DEFAULTS
// ========================================================================
:id: UNSET
:document-id: {id}

// ========================================================================
// AUTHOR & IDENTITY
// ========================================================================
:author-name: Evan Rosado
:author-email-home: evan.rosado@domusdigitalis.dev
:author-email-work: erosado@chla.usc.edu
:author-email-personal: evan.rosado@outlook.com

// ========================================================================
// HOME ENTERPRISE DOMAINS
// ========================================================================
:home-domain: domusdigitalis.dev
:home-domain-internal: inside.domusdigitalis.dev
:home-domain-guest: guest.domusdigitalis.dev
:home-env-name: Home Enterprise ({home-domain})

// ========================================================================
// HOME ENTERPRISE INFRASTRUCTURE
// ========================================================================
// NOTE: These use `home-*` prefix to distinguish from antora.yml's
// top-level `ise-*`, `vault-*` etc. which are the canonical short names.
// antora.yml: {ise-ip}, {vault-hostname} — used in most docs
// attributes.adoc: {home-ise-01-ip}, {home-ise-pan-ip} — used when
// distinguishing cluster nodes or specifying the home lab context.
// ========================================================================

// ISE Cluster (Home)
:home-ise-version: 3.3
:home-ise-pan-ip: 10.50.1.21
:home-ise-pan-host: ise-02.inside.domusdigitalis.dev
:home-ise-01-ip: 10.50.1.20
:home-ise-01-host: ise-01.inside.domusdigitalis.dev
:home-ise-02-ip: 10.50.1.21
:home-ise-02-host: ise-02.inside.domusdigitalis.dev

// DNS (BIND)
:home-dns-primary: 10.50.1.90
:home-dns-secondary: 10.50.1.1
:home-bind-ip: 10.50.1.90
:home-bind-host: bind-01.inside.domusdigitalis.dev

// Active Directory
:home-ad-server: HOME-DC01.inside.domusdigitalis.dev
:home-ad-ca: HOME-ROOT-CA

// Network (VyOS replaced pfSense 2026-03-07)
:home-vyos-ip: 10.50.1.2
:home-vyos-host: vyos-01.inside.domusdigitalis.dev
:home-switch-ip: 10.50.1.10
:home-wlc-ip: 10.50.1.40
:home-wlc-host: wlc.inside.domusdigitalis.dev

// Storage
:nas-ip: 10.50.1.70
:nas-name: nas-01
:nas-nfs-path: /volume1/ise_backups

// ========================================================================
// PERSONAL PROJECTS
// ========================================================================
:prj-ipsk-home: PRJ-ISE-IPSK-HOME-ANTORA
:prj-home-linux: PRJ-ISE-HOME-LINUX-ANTORA
:prj-home-lab: PRJ-ISE-HOME-LINUX-ANTORA
:prj-netapi: PRJ-NETAPI-ANTORA
:prj-secrets: PRJ-SECRETS
:prj-recovery: PRJ-RECOVERY
:prj-infra-ops: PRJ-INFRA-OPS-ANTORA

// ========================================================================
// PERSONAL TOOLS
// ========================================================================
:tool-netapi: netapi (Personal ISE automation CLI)
:tool-dsec: dsec (Secrets management)
:tool-ansible: Ansible
:tool-git: Git

[d2]
....
ise: "{ise-hostname}" {
  shape: rectangle
  label: "ISE {ise-version} patch {ise-patch}"
}
vault: "{vault-url}" {
  shape: cylinder
}
dns: "{dns-server}"
ntp: "{ntp-server}"

ise -> vault: "PKI enrollment"
ise -> dns:   "resolution"
ise -> ntp:   "sync"
....
The …​. passthrough delimiter is required inside AsciiDoc source blocks that contain curly braces — it prevents Asciidoctor from treating diagram content as attribute references before Kroki sees it. Use …​. for diagram blocks, ---- for code listings.

Conditional Content Blocks in Pages

Environment-specific warnings

Version-gated content

Debug / draft content (strip from production builds)

Build with asciidoctor -a debug or antora-playbook.yml attribute debug: '' to surface these blocks during development.

Build Commands Reference

# Standalone Asciidoctor — CHLA target
asciidoctor -a env-d001 -o output/doc-chla.html doc.adoc

# Standalone Asciidoctor — Domus target
asciidoctor -a env-d000 -o output/doc-domus.html doc.adoc

# Standalone — debug mode (surfaces ifdef::debug[] blocks)
asciidoctor -a env-d000 -a debug -o output/doc-debug.html doc.adoc

# Antora — flag set in playbook, just run normally
antora antora-playbook.yml

# Antora — override flag at CLI (useful for local testing against a different env)
antora --attribute env-d000 antora-playbook.yml

Attribute Precedence (Antora)

Higher number wins:

Priority Source

1 (lowest)

Hardcoded in AsciiDoc page (\:attr: value)

2

antora.yml component descriptor

3

antora-playbook.yml asciidoc.attributes

4 (highest)

CLI --attribute flag

Use @ suffix on a value to make it soft (lower-priority sources can override):

# antora-playbook.yml
asciidoc:
  attributes:
    ise-version: '3.3@'   # page-level :ise-version: will win over this
    env-d001: ''          # no @ — this is hard, cannot be overridden by page