AsciiDoc Reference

AsciiDoc markup fundamentals for Antora documentation. Headers, code blocks, tables, admonitions, includes, and cross-references.

Document Header

Standard page header with metadata attributes

= Page Title
:description: One-line SEO description
:navtitle: Short Nav Title
:revdate: 2026-04-10
:icons: font

Every Antora page starts with a level-0 heading (=) followed by document attributes. :navtitle: controls sidebar display. Never add :toc: — Antora UI provides the sidebar TOC globally.

Sections and Headings

Section hierarchy — four levels below the title

== Level 2 — Major Section
=== Level 3 — Subsection
==== Level 4 — Detail
===== Level 5 — Rarely needed

Antora generates anchor IDs automatically from section titles. Override with [#custom-id] above the heading.

Text Formatting

Inline formatting — bold, italic, monospace, combined

*bold*  _italic_  `monospace`  *_bold italic_*  `*bold mono*`

Superscript, subscript, and custom roles

H~2~O        (1)
E=mc^2^      (2)
[.lead]      (3)
Opening paragraph with larger font.

1	Subscript with tildes
2	Superscript with carets
3	`.lead` role creates a lead paragraph

Lists

Ordered and unordered lists with nesting

* Unordered item
** Nested item
*** Third level

. First step
.. Sub-step
. Second step

Description list — term/definition pairs

Term:: Definition on same line
Another term::
  Definition on next line, indented

Admonitions

Five admonition types — requires :icons: font in header

NOTE: Informational aside.

TIP: Helpful suggestion.

IMPORTANT: Key requirement.

WARNING: Potential problem.

CAUTION: Data loss risk.

Block admonition — for multi-paragraph content

[WARNING]
====
This is a block admonition.

It can contain multiple paragraphs, lists, and code blocks.
====

Code Blocks

Source block with language hint and callouts

 [source,bash]
 ----
 awk -F: '{print $1, $3}' /etc/passwd  (1)
 ----
 <1> Colon-delimited, prints username and UID

Source block with attribute substitution

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

When a code block contains {attribute} references, add subs=attributes+ to expand them at build time.

Tables

Standard table with header row

[cols="1,3",options="header"]
|===
| Command | Description

| `ls -la`
| List all files with details

| `df -h`
| Disk usage in human-readable format
|===

Table with column alignment and width control

[cols="2,1,3a",options="header"]
|===
| Name | Status | Notes

| Phase 1
| ✅ Done
| Completed on schedule

| Phase 2
| 🟡 Active
| Contains a nested list:

* Item one
* Item two
|===

The a suffix in 3a enables AsciiDoc content (lists, blocks) inside cells.

Cross-References

Same-component xref — full path from pages/ root

xref:codex/bash/heredocs.adoc[Heredocs]
xref:education/rhcsa/index.adoc[RHCSA Track]

Cross-component xref — double colon separates component

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

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

Includes

Include a partial — shared content fragment

include::partial$projects/p16g/summary.adoc[]

Include an example — code-heavy content

include::example$codex/bash/heredocs.adoc[]

Include with tag filtering — extract specific sections

include::example$codex/bash/loops.adoc[tag=for-loop]

Requires # tag::for-loop[] and # end::for-loop[] markers in the source file.

Images

Block image with alt text and dimensions

image::screenshots/ise-dashboard.png[ISE Dashboard, 800]

Inline image in flowing text

Click the image:icons/gear.png[Settings, 20] icon to configure.

Images resolve from modules/ROOT/images/ in Antora.

Conditional Content

ifdef / ifndef — show content based on attribute existence

ifdef::env-github[]
This renders only on GitHub.
endif::[]

ifndef::backend-html5[]
Not HTML5 output.
endif::[]

Useful for rendering differences between Antora and raw GitHub preview.