AsciiDoc Mastery Reference

A progressive learning guide from everyday patterns to advanced techniques. Organized by frequency of use: start with what you’ll use daily, advance to features that unlock powerful documentation capabilities.

This reference assumes you’re writing for Antora-based documentation sites. Some features behave differently in standalone AsciiDoc processing.

Level 1: Daily Essentials

These patterns cover 80% of documentation work. Master these first.

Document Header

Every .adoc file starts with a header:

= Page Title
:description: SEO description shown in search results
:navtitle: Short Nav Title
:icons: font
Attribute Purpose

:description:

Meta description for SEO and link previews

:navtitle:

Shorter title for navigation sidebar

:icons: font

Enable FontAwesome icons in admonitions
In Antora, do NOT add :toc: attributes. The UI provides the table of contents globally.

Headings

= Document Title (Level 0 - only one per doc)
== Section (Level 1)
=== Subsection (Level 2)
==== Sub-subsection (Level 3)
===== Minor heading (Level 4)
Heading best practices

  • Use sentence case: "Getting started" not "Getting Started"

  • Keep hierarchy logical—don’t skip levels

  • Level 1 (==) is your main content structure

Paragraphs

Just write text. Blank lines separate paragraphs:

First paragraph with some content.

Second paragraph starts after the blank line.
This line continues the second paragraph (no blank line).

Text Formatting

Style Syntax Result

Bold

*bold text*

bold text

Italic

_italic text_

italic text

Monospace

`inline code`

inline code

Bold + Italic

*_both_*

both

Highlight

`#highlighted# `

highlighted

Subscript

H~2~O

H2O

Superscript

x^2^

x2

Links

https://example.com[Click here]              (1)
https://example.com[External link^]          (2)
link:downloads/file.pdf[Download PDF]        (3)
mailto:user@example.com[Email us]            (4)
1 Basic external link
2 Opens in new tab (^ suffix)
3 Relative path (not URL) requires link: prefix
4 Email link

Lists

Unordered list
* Item one
* Item two
** Nested item
*** Deeper nested
* Back to top level
Ordered list
. First step
. Second step
.. Sub-step a
.. Sub-step b
. Third step
Checklist
* [x] Completed task
* [ ] Pending task
* [*] Also completed (alternate syntax)

Renders as:

  • Completed task

  • Pending task

  • Also completed

Description list
Term 1:: Definition for term 1
Term 2:: Definition for term 2
Nested term::: Nested definition

Code Blocks

Basic code block
[source,bash]
----
echo "Hello World"
systemctl restart nginx
----
With title
.Install dependencies
[source,bash]
----
sudo apt update && sudo apt install -y nginx
----
Inline code
Run `systemctl status nginx` to check the service.

Admonitions

Five built-in types:

NOTE: Supplementary information.

TIP: Helpful suggestion.

IMPORTANT: Key information the reader must know.

WARNING: Potential issues to be aware of.

CAUTION: Actions that could cause harm or data loss.

Renders as:

Supplementary information.
Helpful suggestion.
Key information the reader must know.
Potential issues to be aware of.
Actions that could cause harm or data loss.

Images

Block image (standalone)
image::network-diagram.png[Network topology]
With size and alignment
image::logo.png[Company Logo,200,align=center]
Inline image (within text)
Click the image:icon-settings.png[settings,20] icon to configure.

Basic Tables

[cols="1,2,1"]
|===
|Name |Description |Status

|Server 1
|Primary web server
|Active

|Server 2
|Backup server
|Standby
|===

Renders as:

Name Description Status

Server 1

Primary web server

Active

Server 2

Backup server

Standby

Level 2: Intermediate Patterns

Features you’ll use weekly. These improve readability and maintainability.

Attributes (Variables)

The foundation of DRY documentation:

:project-name: Domus Digitalis
:version: 2026
:server-ip: 10.50.1.60

Welcome to {project-name} version {version}.
Connect to {server-ip} for administration.
Table 1. Where to define attributes
Location Scope Use Case

Document header

Entire document

Page-specific values

antora.yml

Entire component

Shared infrastructure values

CLI/API

Build-wide

Environment-specific overrides

Code Blocks with Callouts

[source,bash]
----
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \  (1)
  -H "Content-Type: application/json" \
  -d '{"key": "value"}' \  (2)
  https://api.example.com/endpoint  (3)
----
<1> Authentication header with bearer token
<2> JSON payload
<3> API endpoint URL

Renders as:

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \  (1)
  -H "Content-Type: application/json" \
  -d '{"key": "value"}' \  (2)
  https://api.example.com/endpoint  (3)
1 Authentication header with bearer token
2 JSON payload
3 API endpoint URL

Block Admonitions

For admonitions with complex content:

[WARNING]
====
This operation is destructive:

* All data will be erased
* Backups will not be created automatically
* This cannot be undone

[source,bash]
----
rm -rf /data/*
----
====

Renders as:

This operation is destructive:

  • All data will be erased

  • Backups will not be created automatically

  • This cannot be undone

rm -rf /data/*

Collapsible Blocks

.Click to see the full configuration
[%collapsible]
====
[source,yaml]
----
server:
  port: 8080
  ssl:
    enabled: true
    keystore: /etc/ssl/keystore.jks
----
====

Renders as:

Click to see the full configuration 
server:
  port: 8080
  ssl:
    enabled: true
    keystore: /etc/ssl/keystore.jks

Cross-References

Same page anchor
[[my-anchor]]
== Section Title

Later: see <<my-anchor>> or <<my-anchor,custom text>>.
Same component (Antora)
xref:other-page.adoc[Other Page]
xref:folder/nested.adoc[Nested Page]
\xref:page.adoc#section-id[Specific Section]
Different component (Antora)
xref:infra-ops::runbooks/vault.adoc[Vault Runbook]
xref:netapi:ROOT:cli/ise.adoc[ISE CLI Reference]

Includes (Antora)

Include a partial (reusable content)
include::partial$security-warning.adoc[]
Include an example (code file)
[source,bash]
----
include::example$scripts/backup.sh[]
----
Include specific lines
include::example$config.yaml[lines=10..25]
Table 2. Antora resource directories
Prefix Directory

partial$

modules/ROOT/partials/

example$

modules/ROOT/examples/

image$

modules/ROOT/images/

attachment$

modules/ROOT/attachments/

Table Column Formatting

[cols="2,1,1"]           (1)
[cols="<1,^2,>1"]        (2)
[cols="1a,2"]            (3)
[cols="1h,2"]            (4)
1 Proportional widths (2:1:1)
2 Alignment: < left, ^ center, > right
3 a = AsciiDoc content in cells
4 h = header style column
Table with header row
[cols="1,2",options="header"]
|===
|Name |Description

|Item 1 |First item description
|Item 2 |Second item description
|===

Sidebar Blocks

****
This is a sidebar block.

Use for supplementary content, tips, or asides that shouldn't interrupt the main flow.
****

Renders as:

This is a sidebar block.

Use for supplementary content, tips, or asides that shouldn’t interrupt the main flow.

Quote Blocks

[quote, Grace Hopper]
____
The most dangerous phrase in the language is, "We've always done it this way."
____

Renders as:

The most dangerous phrase in the language is, "We’ve always done it this way."

— Grace Hopper

Keyboard, Button, and Menu Macros

Requires :experimental: in header:

Press kbd:[Ctrl+Shift+P] to open command palette.
Click btn:[Save] to confirm.
Select menu:File[Export > PDF].

Renders as:

Press Ctrl+Shift+P to open command palette. Click Save to confirm. Select File  Export  PDF.

Level 3: Advanced Features

Features that unlock powerful documentation patterns. Use when basic features aren’t enough.

Attribute References in Code Blocks

By default, {attributes} don’t resolve in code blocks. Enable with subs:

[source,bash,subs="attributes+"]
----
export VAULT_ADDR="{vault-addr}"
curl -s {vault-addr}/v1/sys/health
----
Table 3. Common subs values
Value Effect

attributes+

Add attribute substitution

quotes+

Add quote processing (bold)

attributes,quotes

Replace defaults with these only

none

Disable all substitutions

Conditional Content

Include if attribute is set
Include if attribute is NOT set
TIP: This is the development version. Things may change.
Single-line form
Multiple conditions (OR - any attribute)
This appears in HTML5 OR PDF output.
Multiple conditions (AND - all attributes)

ifeval: Expression Evaluation

For comparisons beyond simple presence checks:

This content is HTML5-specific.
Table 4. Available operators
Operator Meaning

== / !=

Equal / Not equal

< / <=

Less than / Less or equal

> / >=

Greater than / Greater or equal
Both sides must be same type. Quote strings: "{attr}" == "value"

Include with Tags

Mark regions in source files:

#!/bin/bash
# tag::setup[]
export VAULT_ADDR="https://vault.example.com:8200"
# end::setup[]

# tag::main[]
vault kv get secret/data
# end::main[]

# tag::cleanup[]
unset VAULT_TOKEN
# end::cleanup[]

Include specific tags:

.Setup phase
[source,bash]
----
include::example$vault-script.sh[tag=setup]
----

.Main operation
[source,bash]
----
include::example$vault-script.sh[tag=main]
----
Multiple tags
include::example$script.sh[tags="setup;main"]
Exclude tags
include::example$script.sh[tags="!cleanup"]

Include with Level Offset

Adjust heading levels of included content:

= Main Document

include::chapter.adoc[leveloffset=+1]

The = Heading in chapter.adoc becomes == Heading in the output.

Counter Attributes

Auto-incrementing counters for numbering:

{counter:step}. Configure the server     (1)
{counter:step}. Install dependencies     (2)
{counter:step}. Start the service        (3)
1 Outputs: 1. Configure the server
2 Outputs: 2. Install dependencies
3 Outputs: 3. Start the service
Alphabetic counters
Appendix {counter:appendix:A}: Introduction
Appendix {counter:appendix}: Configuration
Appendix {counter:appendix}: Troubleshooting
Display without incrementing
Step {counter:num}: Do something
Reminder: We're on step {counter2:num}  (1)
Step {counter:num}: Do next thing
1 counter2 displays current value without incrementing

Intrinsic Attributes

Built-in attributes populated automatically:

Attribute Value Example

reference/asciidoc-mastery

Filename (no extension)

backup-strategy

modules/ROOT/pages/reference/asciidoc-mastery.adoc

Full file path

/home/user/docs/backup.adoc

modules/ROOT/pages/reference

Directory path

/home/user/docs

2026-04-08

Current date

2026-02-25

05:25:52 UTC

Current time

14:30:00

2026-04-08 05:25:52 UTC

Date and time

2026-02-25 14:30:00

2.0.23

Processor version

2.0.20

html5

Output format

html5

.html

Output extension

.html
Practical use
Document: {docname}
Generated: {localdate} at {localtime}

Character Replacement Attributes

Special characters as attributes:

Attribute Character Use Case

 

Non-breaking space

Keep together: 10 GB

​

Zero-width space

Allow breaks: super​long​word

/

Nothing

Empty table cells

Space

Force space in macros

⁠

Word joiner

Prevent breaks
Table 5. Typographical characters
Attribute Character

“ / ”

" "

‘ / ’

' '

°

°

+

+

'

'
Table 6. Escaping syntax characters
Attribute Escapes

*

* (bold marker)

`

` ` ` (monospace)

^

^ (superscript)

~

~ (subscript)

Advanced Tables

AsciiDoc content in cells
[cols="1,2a"]
|===
|Feature |Example

|Nested list
|
* Item one
* Item two
* Item three

|Code block
|
[source,bash]

echo "hello"

|===
Column and row spans
|===
|A |B |C

3+|This cell spans all 3 columns

.2+|Row span
|Normal
|Normal

|Also normal
|Also normal
|===
Syntax Effect

3+|

Span 3 columns

.2+|

Span 2 rows

2.3+|

Span 2 columns AND 3 rows
CSV data table
[%header,format=csv]
|===
Name,IP,Role
vault-01,10.50.1.60,Primary
vault-02,10.50.1.61,Standby
|===
Nested tables
[cols="1,2"]
|===
|Outer
a|
[cols="1,1"]
!===
!Inner !Table
!A !B
!===
|===

Note: Nested tables use !=== instead of |===.

Text Spans and Roles

Apply CSS classes to inline text:

[.underline]#Underlined text#
[.line-through]#Strikethrough text#
[.big]#Larger text#
[.small]#Smaller text#

[.underline.line-through]#Combined styles#
Table 7. Built-in roles
Role Effect

[.underline]

Underline

[.overline]

Overline

[.line-through]

Strikethrough

[.nobreak]

Prevent word breaks

[.nowrap]

Prevent line wrap

[.pre-wrap]

Preserve whitespace
Role on blocks
[.lead]
This paragraph gets "lead" styling—larger intro text.

[.text-center]
====
This block is centered.
====

Pass Macro (Passthrough)

Control substitutions on inline content:

pass:[<b>Raw HTML</b>]                    (1)
pass:q[*bold* inside passthrough]         (2)
pass:a[Server: {server-ip}]               (3)
pass:c,a[<{email}>]                       (4)
1 No substitutions—raw to output
2 q = quotes (bold/italic work)
3 a = attributes resolve
4 Multiple: c (special chars) + a (attributes)
Table 8. Substitution codes
Code Name Effect

c

specialchars

Escape <, >, &

q

quotes

Process bold, italic

a

attributes

Resolve {attr}

r

replacements

-> becomes →

m

macros

Process image:, link:, etc.

p

post_replacements

Line break processing

Passthrough Blocks

For raw content blocks:

++++
<div class="custom-html">
  <p>Raw HTML passed directly to output</p>
</div>
++++

Level 4: Expert Techniques

Advanced patterns for complex documentation systems.

Substitution Order

AsciiDoc applies substitutions in this order:

  1. Special characters (<, >, &)

  2. Quotes (bold, italic)

  3. Attributes ({name})

  4. Replacements (-> → →)

  5. Macros (image::, xref:)

  6. Post-replacements (line breaks)

Understanding this helps debug why content doesn’t render as expected.

Attribute Precedence

When same attribute is defined multiple places:

CLI/API (hard-set) > Document > CLI/API (soft-set)
Soft-set modifier
asciidoctor -a version=1.0@   (1)
asciidoctor -a version=1.0    (2)
1 @ suffix = document can override
2 No suffix = locked, document cannot override

Block Nesting

When nesting same-type blocks, vary delimiter length:

.Outer example
======
Content in outer.

.Inner example
====
Content in inner.
====

Back to outer.
======

Open Block Flexibility

Open blocks (--) can become any type with a style attribute:

[source,python]
--
print("Acts like source block")
--

[quote]
--
Acts like quote block.
--

[sidebar]
--
Acts like sidebar block.
--

STEM (Math Notation)

Enable in header:

:stem:              (1)
:stem: latexmath    (2)
1 Default to AsciiMath
2 Default to LaTeX
Inline math
The quadratic formula: stem:[x = (-b pm sqrt(b^2 - 4ac)) / (2a)]

Using LaTeX: latexmath:[E = mc^2]
Block math
[stem]
++++
sum_(i=1)^n i = (n(n+1))/2
++++
Table 9. AsciiMath vs LaTeX comparison
AsciiMath LaTeX

sqrt(x)

\sqrt{x}

x^2

x^2

sum_(i=1)^n

\sum_\{i=1}^{n}

int_0^1

\int_0^1

(a+b)/c

\frac\{a+b}{c}

alpha, beta

\alpha, \beta

Footnotes

Important statement.footnote:[Supporting reference here.]

Reusable footnote.footnote:fn1[This footnote can be referenced again.]

Later reference.footnote:fn1[]

Index Terms

For generated indexes (PDF, EPUB):

((Vault)) is used for secrets management.  (1)

(((PKI, certificates, TLS)))               (2)
This section covers TLS certificates.

A visible term indexterm:[indexing]        (3)
1 Visible term added to index
2 Hidden triple-level index entry
3 indexterm macro for hidden entries

Document Includes with Conditionals

ifdef::include-appendix[]
include::appendix.adoc[]
endif::[]

Custom Block Delimiters

Create your own patterns:

[source,bash]
------
#!/bin/bash
echo "Six-dash delimiter"
------

Useful when content contains the standard delimiter.

Escaping AsciiDoc Syntax

Backslash escaping
\*not bold*
\_not italic_
\`not monospace`
\ifdef::attr[]   <-- literal, not processed
Passthrough for complex escaping
pass:[*literal asterisks*]
+++**not bold**+++

Practical Patterns

Real-world patterns that combine multiple features.

DRY Infrastructure Documentation

Define in antora.yml:

asciidoc:
  attributes:
    vault-addr: https://vault-01.inside.domusdigitalis.dev:8200
    vault-port: 8200
    homedc-ip: 10.50.1.50

Use everywhere:

[source,bash,subs="attributes+"]
----
export VAULT_ADDR="{vault-addr}"
kinit user@DOMAIN -S host/{homedc-ip}
----

Platform-Specific Instructions

[tabs]
====
Linux::
+
[source,bash]
----
sudo apt install vault
----

macOS::
+
[source,bash]
----
brew install vault
----

Windows::
+
[source,powershell]
----
choco install vault
----
====
Tabs require Antora UI support or Asciidoctor Tabs extension.

Reusable Warning Blocks

Create partials/production-warning.adoc:

[CAUTION]
====
*Production Environment*

This operation affects live systems:

* Ensure maintenance window is scheduled
* Verify backup completed successfully
* Have rollback plan ready
====

Include where needed:

include::partial$production-warning.adoc[]

Version-Aware Content

NOTE: Parallel processing is available in version 2026+.

Auto-Generated Timestamps

.Document Information
[cols="1,2"]
|===
|Generated |{localdatetime}
|Source |{docname}{docfilesuffix}
|Processor |Asciidoctor {asciidoctor-version}
|===

Command with Output

.Check vault status
[source,bash]
----
vault status
----

.Expected output
[source,text]
----
Key             Value
---             -----
Seal Type       shamir
Initialized     true
Sealed          false
----

Before/After Comparison

[cols="1a,1a"]
|===
|Before |After

|
[source,yaml]

server: port: 80

|
[source,yaml]

server: port: 443 ssl: true

|===

Common Mistakes and Fixes

Mistake Fix

:toc: left in Antora docs

Remove it—Antora UI provides TOC

{attribute} in code blocks

Add subs="attributes+"

xref:page.adoc[] cross-component

Use xref:component::page.adoc[]

include::file.adoc[] in Antora

Use include::partial$file.adoc[]

Hardcoded IPs in docs

Define in antora.yml, reference with {attr}

Missing blank line before list

AsciiDoc needs blank line to start list context

endif:: without brackets

Must be endif::[]

Forward attribute reference

Attributes must be defined before use

Contributing to AsciiDoc Community

Welcome to the community! Here’s how to contribute:

Where to Contribute

Project Repository

AsciiDoc Language

github.com/asciidoctor/asciidoc-lang

Asciidoctor (Ruby)

github.com/asciidoctor/asciidoctor

Asciidoctor.js

github.com/asciidoctor/asciidoctor.js

Antora

gitlab.com/antora/antora

Asciidoctor PDF

github.com/asciidoctor/asciidoctor-pdf

Asciidoctor Diagram

github.com/asciidoctor/asciidoctor-diagram

Contribution Ideas

Documentation

  • Fix typos and unclear explanations

  • Add examples for undocumented features

  • Translate documentation

  • Write tutorials and guides

Code

  • Fix bugs (check issue trackers)

  • Implement feature requests

  • Improve error messages

  • Add tests for edge cases

Community

  • Answer questions on GitHub Discussions

  • Help triage issues

  • Review pull requests

  • Share your AsciiDoc projects

Getting Started

  1. Fork the repository

  2. Read CONTRIBUTING.md

  3. Find a "good first issue" label

  4. Make changes in a branch

  5. Submit a pull request

  6. Respond to review feedback

Start with documentation contributions—they’re welcoming to newcomers and help you learn the codebase.

Quick Reference Card

Most Common Patterns

= Title                            <-- Document title
== Section                         <-- Level 1 heading
*bold* _italic_ `code`             <-- Inline formatting
https://url[text]                  <-- Link
image::file.png[alt]               <-- Block image
\xref:page.adoc[text]              <-- Cross-reference
\{attribute-name}                  <-- Attribute reference
\include::partial$file.adoc[]      <-- Include partial
[source,lang]                      <-- Code block start
----                               <-- Code block delimiter
NOTE: text                         <-- Admonition

Delimiter Reference

Delimiter Block Type Use

----

Listing/Source

Code blocks

…​.

Literal

Preformatted text

====

Example

Examples, collapsibles

**

Sidebar

Supplementary content

__

Quote/Verse

Quotations

Passthrough

Raw HTML

--

Open

Flexible (any style)

////

Comment

Hidden content

|===

Table

Tabular data

Attribute Quick Reference

Syntax Purpose

:name: value

Set attribute

:!name:

Unset attribute

{name}

Reference attribute

ifdef::name[]

If attribute set

ifndef::name[]

If attribute not set

ifeval::[expr]

If expression true

Resources

Official Documentation

Community

Learning Resources