STD-004: AsciiDoc Conventions

Authoring rules for every .adoc file across all domus spoke repositories. These conventions ensure build reliability, attribute consistency, and cross-component xref resolution.

Principles

  1. Attributes over literals. Mutable values (IPs, hostnames, ports, paths, policy names) MUST be expressed as {attribute-name}, never hardcoded. This enables single-source-of-truth updates.

  2. Verify before use. Every attribute MUST be confirmed to exist in antora.yml before being used in a document. Assumed attributes are the #1 cause of build failures.

  3. Build before commit. No commit passes without a clean build check. Broken builds block the entire Cloudflare Pages deploy pipeline.

  4. No inline TOC. Antora UI provides a global sidebar TOC. Adding :toc: to any page creates a duplicate.

  5. No credentials in documents. Redact with <REDACTED>. gopass paths and Vault policy names are acceptable; secret values are not.

Requirements

  1. Every .adoc file MUST NOT contain :toc:, :toclevels:, or :toc-title: attributes.

  2. Every mutable value (IP, hostname, port, MAC, VLAN, path, policy name) MUST use an {attribute} reference, never a hardcoded literal.

  3. Before using any attribute, the author MUST verify it exists: grep -i "<term>" docs/asciidoc/antora.yml.

  4. Code blocks containing {attribute} references MUST include subs=attributes+.

  5. Before every commit touching .adoc files: make 2>&1 | grep -E "WARN|ERROR" MUST return clean.

  6. Credentials, tokens, and secret values MUST NOT appear in any document. Redact with <REDACTED>.

  7. Cross-references in nested directories MUST use full paths from pages/ root. Relative xrefs fail in subdirectories.

  8. Cross-component xrefs MUST use double-colon syntax: Text.

Pre-Write Checklist

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

# 2. Search for specific attribute before using it
grep -i "<term>" docs/asciidoc/antora.yml

# 3. Build before committing
make 2>&1 | grep -E "WARN|ERROR"

Document Header Template

Every page MUST include at minimum:

= Page Title
:description: Brief description
:navtitle: Short Nav Title
:icons: font

No :toc: attributes. No hardcoded values in the header.

Attribute Usage in Code Blocks

// Correct — subs=attributes+ enables attribute interpolation
[source,bash,subs=attributes+]
\----
ssh {person-evan}@{domain}@{ws-aw-hostname}
\----

// Wrong — attributes render as literal text without subs
[source,bash]
\----
ssh {person-evan}@{domain}@{ws-aw-hostname}
\----

Cross-Reference Rules

// Same component — full path from pages/
xref:education/rhcsa/index.adoc[RHCSA]

// Cross-component — double colon
xref:infra-ops::runbooks/vyos-deployment.adoc[VyOS Deployment]
xref:ise-linux::02-pki/certificate-enrollment.adoc[Cert Enrollment]

// WRONG — relative xref in subdirectory (will fail)
xref:capitulo-001.adoc[Chapter I]

// CORRECT — full path
xref:education/literature/quijote/primera-parte/capitulo-001.adoc[Chapter I]

Compliance

Check Method Pass Criterion

No inline TOC

grep -r ':toc:' pages/

Zero matches

No hardcoded IPs

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

Zero matches (excluding comments and attribute references)

Build clean

make 2>&1 | grep -E 'WARN|ERROR'

Zero output

Attributes verified

Every {attribute} in new content exists in antora.yml

grep confirms presence

No credentials

`grep -riE 'password

token

secret

apikey' pages/ | grep -v REDACTED | grep -v gopass`

Zero real credentials

Exceptions

None. All requirements apply unconditionally to every .adoc file in every domus spoke repository.

Related