STD-028: AsciiDoc Feature Catalog

Definitive catalog of every AsciiDoc feature authorized for use across domus repositories — Antora pages and standalone build-adoc documents alike. Each feature includes implementation syntax, rendering behavior, and scope (Antora, standalone, or both).

Purpose

STD-004 governs conventions (what to avoid, how to verify). This standard governs features — the full palette of AsciiDoc constructs available to authors, with implementation syntax for each.

The reference page pages/reference/antora-asciidoc-features.adoc served as an informal inventory. This standard supersedes it as the authoritative, maintained catalog.

Scope

Context Applies

Antora pages (docs/modules/ROOT/)

All features unless marked Standalone only

Standalone documents (data/)

All features unless marked Antora only

Both

Default — most features work in both contexts

Document Attributes

Required Header (Antora)

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

No :toc: — Antora UI provides sidebar TOC globally.

Required Header (Standalone)

= Document Title
:description: Brief description
:icons: font
:toc: left
:toclevels: 2
:sectnums:
:source-highlighter: rouge

:toc: left and :sectnums: are permitted in standalone documents only.

Global Attributes (antora.yml)

Attribute Purpose Value

icons

Icon rendering

font (Font Awesome)

experimental

Enable ]+btn:[, menu:[]

Enabled

source-highlighter

Syntax highlighting

highlight.js (Antora), rouge (standalone)

sectanchors

Clickable anchors on headings

Enabled

sectlinks

Headings as links

Enabled

hide-uri-scheme

Hide https:// in URLs

Enabled

attribute-missing

Warn on undefined attributes

warn

Admonitions

Standard Admonitions

Five built-in types. Inline or block form.

Inline
TIP: Use `subs=attributes+` for code blocks with attributes.
Block
[NOTE]
====
Block admonition with multiple paragraphs.
====

Custom-Role Admonitions

Admonitions with custom CSS roles for semantic styling. The role appears after the dot: [TYPE.role].

Syntax Semantic Purpose Use Case

[NOTE.cervantes]

Primary source text

Cervantes quotations, original texts

[TIP.gramatica]

Linguistic analysis

Vocabulario tables, grammar notes

[IMPORTANT.retorica]

Rhetorical/literary analysis

Dispositio, figures, metaliterature

[WARNING.dudas]

Questions and unknowns

Study questions, open investigations

[NOTE.capitulo]

Structural container

Chapter-level wrapper with collapsible body
Implementation — custom-role admonition with sidebar body
.Texto de Cervantes
[NOTE.cervantes]
****
Full text content here. The sidebar block (****) provides
visual separation within the admonition.
****
Custom roles require corresponding CSS in the UI bundle or build-adoc theme to render distinctly. Without CSS, they render as their base admonition type.

Admonition Color Selection

Each admonition type provides a distinct color. Choose the type by the color you want, not the label.

Type Color Icon Override Caption

[NOTE]

Blue

[NOTE,caption=" "]

[TIP]

Green

[TIP,caption=" "]

[WARNING]

Yellow/Orange

[WARNING,caption=" "]

[IMPORTANT]

Red

[IMPORTANT,caption=" "]

[CAUTION]

Orange/Red

[CAUTION,caption=" "]

Admonition Caption Override

Replace the default icon with any Font Awesome icon while keeping the admonition’s color:

.Authentication Flow — Target State
[TIP,caption="icon:project-diagram[] "]
====
Content gets TIP's green color with a project-diagram icon.
====

The caption attribute replaces the icon and label. The trailing space after `[] ` prevents the caption from colliding with the title.

Tables Inside Admonitions

Tables placed directly inside ==== admonition blocks inherit the admonition’s background color. Do NOT wrap in **** — the sidebar block resets the background to white.

.Command Reference — SAML IdP
[TIP]
====
[cols="3,4", options="header", stripes=even]
|===
| Command | Purpose

| `saml idp https://...`
| Entity ID from Entra

| `trustpoint idp EntraID-SAML-IdP`
| Trustpoint with Entra signing cert
|===
====

Use different admonition types to color-code command sections:

  • [TIP] (green) — primary configuration commands

  • [NOTE] (blue) — reference/informational commands

  • [WARNING] (yellow) — rollback/emergency commands

  • [IMPORTANT] (red) — destructive or irreversible commands

Admonition Contour — Bordered Table Wrapper

An admonition wrapping a table provides a colored border (contour) around the entire section — title, table, and any nested content. This is the pattern that gives tables visual framing beyond stripes=even.

.Progreso de Estudio — Primera Parte (1605)
[NOTE.progress]
========                                      (1)

.Ver tabla de progreso
[%collapsible]
=======                                       (2)
[cols="1,3,1", options="header"]
|===
| Cap. | Título | Estado

| I | Que trata de la condición... | ▓▓▓▓▓░░░░░ 50%
| II | Que trata de la primera... | ░░░░░░░░░░ 0%
|===
=======

========
1 Eight = for the outer admonition — provides the colored border/contour
2 Seven = for the inner collapsible — must differ from outer to avoid premature closure

The admonition type controls the contour color:

  • [NOTE] or [NOTE.progress] — blue contour

  • [TIP] — green contour

  • [WARNING] — yellow/orange contour

  • [IMPORTANT] — red contour

The .Title above the admonition renders as a caption outside the contour. The collapsible inside keeps large tables folded by default.

This pattern is distinct from "Tables Inside Admonitions" (previous section) which uses ==== for simple inline tables. The contour pattern uses deeper nesting (======== / =======) when the table needs both a colored border AND collapsible behavior.

Icon-Prefixed Table Cells

Font Awesome icons inside table cells for visual status and categorization:

[cols="1,3", stripes=even]
|===
| Component | Detail

| icon:server[] ASA
| AnyC-FP-2140-1 (active/standby)

| icon:cloud[] Entra ID
| CHLA tenant — Enterprise App

| icon:certificate[] VPN Cert
| vpn.example.org — expires 2026-07-28
|===

Progress Bars

Unicode block characters for visual percentage tracking in tables. Each ▓ = 10%, each ░ = empty.

[cols="1,3,1", options="header", stripes=even]
|===
| Phase | Description | Progress

| Phase 0
| Preparation
| ▓▓▓░░░░░░░ 30%

| Phase 1
| Configuration
| ░░░░░░░░░░ 0%
|===

Full scale:

░░░░░░░░░░ 0% · ▓▓▓░░░░░░░ 30% · ▓▓▓▓▓░░░░░ 50% · ▓▓▓▓▓▓▓░░░ 70% · ▓▓▓▓▓▓▓▓▓▓ 100%

Update by replacing ░ with ▓ left to right as work progresses.

Nested Blocks — Admonition + Collapsible

A chapter container pattern: outer admonition wraps a collapsible block. Requires different delimiter lengths to avoid ambiguity.

.Chapter Title — Description
[NOTE.capitulo]
======                          (1)
_Primera Parte (1605) — 11 parrafos_

.Abrir capitulo completo
[%collapsible]
====                            (2)

include::partials/01-first-section.adoc[]

include::partials/99-mis-dudas.adoc[]

====
======
1 Six = for the outer admonition delimiter
2 Four = for the inner collapsible block

The outer block uses ====== (six) and the inner uses ==== (four). AsciiDoc matches delimiters by length — mixing lengths prevents premature closure.

Collapsible Blocks

Expandable/foldable content. The reader clicks to reveal.

.Click to expand
[%collapsible]
====
Hidden content revealed on click.
====

For code blocks inside collapsible:

.script.sh (click to expand)
[%collapsible]
====
[source,bash]

#!/bin/bash echo "Hello"

====

Block Types

Sidebar Block (****)

Supplementary content with visual border. Used as the body of custom-role admonitions.

.Title
****
Sidebar content here.
****

All Delimiters

Block Delimiter Purpose Status

Source/Listing

----

Syntax-highlighted code

Active

Literal

…​.

Preformatted, no formatting

Active

Sidebar

****

Supplementary content

Active

Example

====

Examples, admonitions, collapsible

Active

Quote

____

Block quotations

Available

Verse

[verse] + ____

Poetry/verse formatting

Available

Passthrough

Raw HTML/SVG

Available

Comment

////

Hidden from output

Active

Open

--

Generic container

Available

Table

|===

Data tables

Active

Tables

Column Specifiers

Spec Meaning Example

1,2,3

Proportional widths

cols="1,2,3"

<

Left align

cols="<,^,>"

^

Center align

cols="^2"

>

Right align

cols=">1"

a

AsciiDoc content in cells

cols="1a,2a"

h

Header style column

cols="h,1,1"

e

Emphasis (italic)

cols="e,1"

m

Monospace

cols="m,1"

s

Strong (bold)

cols="s,1"

Striped Tables

Alternating row colors for readability. Set via the stripes option.

[cols="1,2,3", options="header", stripes=even]
|===
| Palabra | Significado | Nota

| _linaje_ | Familia, estirpe | Registro nobiliario
| _mezquino_ | Tacaño, avaro | Del árabe _miskīn_
|===

Valid values: even (default off), odd, all, hover.

Cell Spanning

|===
| A | B | C

2+| Spans 2 columns | C only

.2+| Spans 2 rows
| B1
| B2

2.3+| Spans 2 cols, 3 rows
|===

Table Options

[cols="1,2,3", options="header,footer,autowidth"]
|===
| Header 1 | Header 2 | Header 3
| Cell | Cell | Cell
| Footer 1 | Footer 2 | Footer 3
|===

Lists

Standard Lists

* Unordered item
** Nested

. Ordered item
.. Sub-item

Term:: Definition
Nested term::: Nested definition

Checklists

* [x] Completed
* [ ] Pending
* [*] Also completed

[%interactive]            (1)
* [ ] Clickable in HTML
* [ ] User can toggle
1 [%interactive] makes checkboxes clickable in HTML output

Glossary Lists

Definition list with [glossary] role. Renders with glossary semantics — terms as entries, definitions as explanations.

[glossary]

linaje:: Familia, estirpe, origen genealógico.

estrecheza:: Pobreza, escasez. Forma del XVI (hoy: «estrechez»).

mezquino:: Tacaño, avaro. Del árabe _miskīn_.

Wrap in a custom-role admonition for visual context:

.Glosario — Capítulo XXXIX
[TIP.gramatica]
****

[glossary]

linaje:: Familia, estirpe.

mezquino:: Tacaño, avaro.

****

Q&A Lists

Question-and-answer format with [qanda] role. Questions render as numbered items with answers indented beneath.

[qanda]
¿Por qué Cervantes elige las Montañas de León?::
_Respuesta aquí._

¿Qué relación hay con el hijo pródigo bíblico?::
_Respuesta aquí._

Wrap in a custom-role admonition:

.Mis Dudas — Capítulo XXXIX
[WARNING.dudas]
****

[qanda]
¿Primera pregunta?::
_Respuesta._

¿Segunda pregunta?::
_Respuesta._

****

Footnotes

Inline Footnotes

Single-use footnote at point of reference.

La naturaleza fue liberal footnote:[Acepción clásica: «generoso».]
con el cautivo.

Reusable Footnotes

Named footnote defined once, referenced multiple times. First occurrence defines; subsequent occurrences reference.

// First occurrence — defines the footnote
Del árabe _miskīn_. footnote:mezquino[Arabismo en boca de un cautivo.]

// Later occurrence — references by name only
Repite _mezquino_ footnote:mezquino[] aquí.

The [1] syntax creates the definition. [1] (empty brackets) creates a back-reference to the same footnote.

Text Formatting

Inline Markup

Markup Renders As Notes

*bold*

bold

Strong emphasis

_italic_

italic

Emphasis

`monospace`

monospace

Code/literal

*_bold italic_*

bold italic

Combined

^super^

super

Superscript

~sub~

sub

Subscript

#highlight#

highlight

Marked text

[.line-through]#struck#

struck

Strikethrough

[.underline]#underlined#

underlined

Underline

Paragraph Roles

[.lead]
*§1 — El origen del cautivo*

The [.lead] role renders the paragraph in a larger, emphasized font. Use for section openers or paragraph headings within a block.

Block Titles

Every block type accepts a .Title label. The title renders above the block as a caption.

.Vocabulario — §1
[TIP.gramatica]
****
Content here.
****

.script.sh — Pipeline Operations (click to expand)
[%collapsible]
====
Content here.
====

Callouts

Source Block Callouts

Numbered markers in code, explained below.

[source,bash]
----
vault write pki_int/issue/domus-client \ (1)
  common_name="host.example.com" \ (2)
  ttl="8760h" (3)
----
<1> PKI mount path and role
<2> Common name for certificate
<3> Time to live (1 year)

Comment-Style Callouts (Copy-Safe)

[source,bash]
----
export VAULT_ADDR="https://vault.example.com" (1)
vault login -method=ldap username="$USER" (2)
----
<1> Set Vault address
<2> Authenticate with LDAP

Callouts Outside Source Blocks

Callout lists can follow any block — including sidebar blocks inside admonitions. Use circled number Unicode characters for visual markers in prose.

.Gramática del Siglo de Oro — §1
[TIP.gramatica]
****
* *①* **Enclítico**: _gastalla_ = gastar + la.
* *②* **Subjuntivo _-ra_**: _lo fuera_ = «lo habría sido».
****
<1> Compare: _conservar_ (modern) vs _gastalla_ (XVI).
<2> Today: «lo habría sido si se hubiera dado maña...».

Circled numbers: ① ② ③ ④ ⑤ ⑥ ⑦ ⑧ ⑨ ⑩

Code Blocks

Basic Source Block

[source,bash]
----
#!/bin/bash
echo "Hello"
----

Attribute Substitution

[source,bash,subs=attributes+]
----
ssh {person-evan}@{ws-aw-hostname}
----

MUST include subs=attributes+ when the block contains {attribute} references.

Pasteable Run Block + Collapsible Source (STD-008)

[source,bash]
\----
bash $(find data -name script.sh) arg1 arg2
\----

.script.sh — Description (click to expand)
[%collapsible]
====
[source,bash]
\----
include::{docdir}/{scripts-dir}/script.sh[]
\----
====

No $ prompt glyphs. Use $(find) for portable paths.

Include Directives

Antora Includes

include::partial$trackers/work/adhoc.adoc[]
include::example$scripts/backup.sh[]

Standalone Includes

include::partials/summary.adoc[]
include::{docdir}/scripts/tool.sh[]

Tagged Regions

Define tags in source:
// tag::carryover[]
| Task 1 | 5 days |
// end::carryover[]
Include specific tag:
include::partial$trackers/work/adhoc.adoc[tag=carryover]
include::partial$file.adoc[tags=p0;p1]

Line Ranges and Level Offset

include::example$script.sh[lines=10..20]
include::partial$section.adoc[leveloffset=+1]

Cross-References

Same Component (Antora)

xref:page.adoc[Link Text]
xref:folder/page.adoc#section[Section Link]

Always use full paths from pages/ root in nested directories.

Cross-Component (Antora)

xref:infra-ops::runbooks/vyos-deployment.adoc[VyOS Runbook]
xref:ise-linux::02-pki/certificate-enrollment.adoc[Cert Enrollment]

Double colon (::) for cross-component references.

Conditional Directives

ifdef::env-d001[]
Sensitive content — only rendered with -a env-d001 flag.
endif::[]

ifndef::env-d001[]
Zeroed fallback — safe for public output.
endif::[]

ifeval::["{backend}" == "html5"]
HTML-specific content.
endif::[]

UI Macros

Require :experimental: attribute.

Macro Purpose Example

Ctrl+C

Keyboard shortcuts

Press Ctrl+C

Save

Buttons

Click Save

File  Export  PDF

Menu navigation

Select File  Export  PDF

Icon Macros

Require :icons: font attribute.

Syntax Use Case

Completed items

Failed/removed

Active status

In progress

Caution

Complete status

Archived

Planned

Status Attribute Icons (antora.yml)

status-active: icon:circle[role=green] Active
status-complete: icon:check-circle[role=blue] Complete
status-archived: icon:archive[role=gray] Archived
status-planned: icon:clock[role=gray] Planned
status-in-progress: icon:spinner[role=blue]
status-done: icon:check[role=green]

Images

Antora Images

image::filename.svg[Alt text,width=100%]

Images resolve from modules/ROOT/images/.

Standalone Images

image::{docdir}/partials/p1-cap-39/images/diagram.svg[Alt text,width=100%]

MUST use {docdir} for absolute path resolution. Standalone builds copy to a temp directory — relative paths break.

STEM (Math/Science)

= Document Title
:stem: asciimath

Inline: stem:[sqrt(4) = 2]

[stem]
++++
sum_(i=1)^n i^3=((n(n+1))/2)^2
++++

latexmath:[\lim_{n \to \infty}\frac{n}{\sqrt[n]{n!}} = e]

Escape Patterns

AsciiDoc interprets {text} as attribute references. Escape with backslash.

Pattern Escaped Context

{print}

\{print}

awk statements

{0}, {1}

\{0}, \{1}

awk field references

{n,m}

\{n,m}

regex quantifiers

{foo:-bar}

\{foo:-bar}

bash parameter expansion

Alternative for complex cases: {print $1}

Compliance

Check Method Pass Criterion

Features render correctly

make (Antora) or make build-data PROJ=name (standalone)

Visual inspection of output

Custom roles have CSS

Verify role exists in UI bundle or theme

Styled distinctly from base type

No :toc: in Antora pages

grep -r ':toc:' docs/modules/ROOT/pages/

Zero matches

Footnotes resolve

Build + check footnote section in output

All [1] back-references link to definitions

Nested blocks use different delimiter lengths

Visual inspection

Outer ======, inner ====

Related

1. text