AsciiDoc Style Guide for Technical Documentation

1. Overview

This guide defines the AsciiDoc formatting standards and conventions for technical documentation. These standards ensure consistency, maintainability, and accessibility across all documentation.

2. Document Structure

2.1. Required Page Structure

Every AsciiDoc page MUST include:

= Page Title
:description: Brief description for metadata
:keywords: comma, separated, keywords

[Optional lead paragraph introducing the topic]

== First Section

Content here...

2.2. Standard Page Attributes

Include these attributes at the top of each page as appropriate:

= Page Title
:description: Page description for SEO and navigation
:keywords: relevant, keywords, here
:page-tags: category1, category2
:page-aliases: old-path.adoc
:sectnums:
:sectlinks:

Attribute Descriptions:

  • :description: - Brief page description for metadata and search engines

  • :keywords: - Comma-separated keywords for searchability

  • :page-tags: - Categories for organizing content

  • :page-aliases: - Redirect paths from old/renamed pages

  • :sectnums: - Enable automatic section numbering

  • :sectlinks: - Make section headings clickable

2.2.1. Table of Contents Attributes (Do NOT Use)

Do NOT include :toc: or :toclevels: attributes in AsciiDoc pages for Antora projects.

  • :toc: - Generates an embedded table of contents within the document

  • :toclevels: - Controls depth of the embedded TOC

Why these should be avoided:

  1. Antora provides its own TOC - Antora’s UI generates a sidebar table of contents automatically. Adding :toc: creates a redundant, duplicate TOC in the page content.

  2. Multi-format publishing - When generating PDFs or eBooks, TOC settings should be configured globally by the build tool (e.g., asciidoctor-pdf -a toc), not per-document. This ensures consistent formatting across all outputs.

  3. Separation of concerns - Content (AsciiDoc files) should focus on content. Presentation decisions like TOC placement belong in the build configuration or UI template.

For PDF/eBook generation:

Configure TOC globally in your build tool:

asciidoctor-pdf -a toc -a toclevels=2 document.adoc

For Antora sidebar TOC depth:

Use the Antora-specific attribute:

:page-toclevels: 2

This controls Antora’s sidebar TOC without embedding a duplicate TOC in the document.

3. Naming Conventions

3.1. File Names

  • Use lowercase with hyphens: api-design.adoc, getting-started.adoc

  • Be descriptive and specific

  • Avoid abbreviations unless universally understood

  • Use consistent naming patterns within the module

  • Always use .adoc extension for AsciiDoc files

Examples:

Good File Names
event-entities.adoc
security-architecture.adoc
getting-started-guide.adoc
api-authentication.adoc
Poor File Names
EventEntities.adoc         # Wrong: Uses PascalCase
security_arch.adoc         # Wrong: Uses underscores
gs-guide.adoc              # Wrong: Uses abbreviation
authentication.txt         # Wrong: Wrong extension

3.2. Heading Conventions

  • Use sentence case for headings (first word capitalized, rest lowercase unless proper nouns)

  • Keep headings concise and descriptive

  • Use consistent heading levels (no skipping levels)

Heading Hierarchy:

= Document Title (Level 0 - used only once at top)

== Main Section (Level 1)

=== Subsection (Level 2)

==== Sub-subsection (Level 3)

===== Detailed subsection (Level 4)

Never skip heading levels. For example, don’t go from == directly to ==== without a === in between.

4. Content Formatting

4.1. Paragraphs

  • Use blank lines to separate paragraphs

  • Keep paragraphs focused on a single idea

  • Use line breaks within paragraphs for readability in source (optional)

This is the first paragraph with a clear, focused idea.

This is the second paragraph discussing a different point.
It can span multiple lines in the source file,
but will render as a single paragraph.

4.2. Lists

4.2.1. Unordered Lists

* First item
* Second item
** Nested item
** Another nested item
* Third item

4.2.2. Ordered Lists

. First step
. Second step
.. Nested step
.. Another nested step
. Third step

4.2.3. Description Lists

Term 1:: Definition of term 1
Term 2:: Definition of term 2
Term 3:: Definition of term 3

4.3. Text Formatting

*bold text* for emphasis

_italic text_ for slight emphasis

`monospace text` for code, commands, or file names

**bold** and __italic__ alternative syntax

^superscript^ text

~subscript~ text

Usage Guidelines:

  • Use bold for important terms on first mention

  • Use italic sparingly for slight emphasis

  • Use monospace for code elements, file paths, commands, variables

  • Avoid overuse of formatting - let content speak for itself

4.4. Code Blocks

Use syntax highlighting with language specification:

[source,java]
----
public class Example {
    private String name;

    public Example(String name) {
        this.name = name;
    }
}
----

Common Language Identifiers:

  • java - Java code

  • python - Python code

  • javascript - JavaScript code

  • bash - Shell scripts

  • sql - SQL queries

  • json - JSON data

  • xml - XML markup

  • yaml - YAML configuration

  • asciidoc - AsciiDoc markup

Code Block Options:

[source,java,linenums]
----
public class Example {
    // Line numbers enabled
}
----

[source,java,highlight=2]
----
public class Example {
    private String highlighted; // This line highlighted
}
----

4.5. Tables

Use pipe-delimited tables with column specifications:

[cols="1,2,1"]
|===
|Header 1 |Header 2 |Header 3

|Cell 1.1
|Cell 1.2
|Cell 1.3

|Cell 2.1
|Cell 2.2
|Cell 2.3
|===

Column Specifications:

  • Numeric values (e.g., 1,2,1) define relative widths

  • Use ^ for center alignment: [cols="1,^2,1"]

  • Use > for right alignment: [cols="1,>2,1"]

  • Use .> for top alignment: [cols="1,.>2,1"]

Table Options:

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

|Item 1
|Description 1
|Active

|Item 2
|Description 2
|Pending
|===

4.6. Links and Cross-References

4.6.1. External Links

https://example.com[Link Text]

https://example.com[Link with Title^] (opens in new window)

Plain URL: https://example.com (auto-linked)

4.6.2. Antora Cross-References

xref:other-page.adoc[Link Text]

xref:other-page.adoc#section-id[Link to Section]

xref:version@component:module:page.adoc[Cross-component Link]

xref:module:page.adoc[Cross-module Link]

Always use xref: syntax for internal documentation links. Never use relative file paths or hardcoded URLs.

4.6.3. Anchor References

[[custom-anchor-id]]
== Section Title

Link to it: <<custom-anchor-id>>

Or: <<custom-anchor-id,Custom Link Text>>

4.7. Images and Diagrams

image::filename.png[Alt Text,width,height]

image::architecture-overview.svg[Architecture Overview Diagram,800]

image::logo.png[Company Logo,100,100,float=right]

Image Best Practices:

  • Always provide descriptive alt text for accessibility

  • Use web-friendly formats: PNG, SVG, JPEG

  • Name images descriptively: architecture-overview.svg, login-flow.png

  • Specify width to control rendering size

  • Use SVG for diagrams when possible (scalable, crisp)

Image Options:

  • align=center - Center the image

  • float=left - Float image to the left

  • float=right - Float image to the right

  • role=thumb - Make image a thumbnail

4.8. Admonitions

Use semantic admonitions appropriately:

[NOTE]
====
Additional information that helps understand the context.
====

[TIP]
====
Helpful suggestion or best practice.
====

[IMPORTANT]
====
Critical information that should not be ignored.
====

[CAUTION]
====
Proceed with care - potential for unintended consequences.
====

[WARNING]
====
Danger or serious risk - may cause data loss or security issues.
====

Admonition Usage Guidelines:

  • NOTE - Supplementary information, background context

  • TIP - Helpful hints, shortcuts, best practices

  • IMPORTANT - Critical information requiring attention

  • CAUTION - Proceed carefully, review before acting

  • WARNING - Serious risk, danger, or potential for loss

Use block syntax (====) for multi-paragraph admonitions. For single-line admonitions, you can use:

NOTE: This is a single-line note.

4.9. Block Elements

4.9.1. Example Blocks

.Example Title
====
This is an example block showing how something works.

It can contain multiple paragraphs and other elements.
====

4.9.2. Sidebar Blocks

.Sidebar Title
****
Sidebar content provides related information without disrupting the main flow.

Use sidebars for:
* Related concepts
* Historical context
* Tangential information
****

4.9.3. Quote Blocks

[quote,Author Name,Source]
____
This is a quoted passage.
____

Or simple quote:
____
This is a quote without attribution.
____

4.9.4. Literal Blocks

....
Literal block - preserves spacing and formatting
No markup processing occurs here
....

[literal]
....
Alternative literal block syntax
....

4.10. Special Elements

4.10.1. Callouts

Use callouts to explain specific lines in code blocks:

[source,java]
----
public class Example {
    private String name; (1)

    public Example(String name) {
        this.name = name; (2)
    }
}
----
<1> Instance variable declaration
<2> Constructor parameter assignment

4.10.2. Keyboard Shortcuts

Press kbd:[Ctrl+S] to save.

Use kbd:[Ctrl+Alt+Delete] for task manager.

4.10.3. Menu Selections

Select menu:File[Save As] to save with a new name.

Navigate to menu:Tools[Options > Advanced] for settings.

4.10.4. Buttons

Click btn:[OK] to continue.

Press the btn:[Submit] button.

5. Document Includes

5.1. Including Files

include::partial$common-prerequisites.adoc[]

include::example$user-authentication.java[]

include::partial$warning-message.adoc[tag=important]

5.2. Include Syntax by Directory

  • partial$ - Include from partials/ directory

  • example$ - Include from examples/ directory

  • attachment$ - Reference attachments/ directory

  • image$ - Include from images/ directory

5.3. Tagged Regions

Define reusable sections with tags:

// In the source file:
\// tag::important[]
This is important content.
\// end::important[]

\// tag::optional[]
This is optional content.
\// end::optional[]

// In the including file:
include::source.adoc[tag=important]

6. Antora Integration

This style guide focuses on AsciiDoc formatting and content standards. For Antora-specific configuration, module management, and project structure, see the Antora Configuration Guide.

6.1. Antora Cross-References

When writing Antora documentation, use the xref: syntax for all internal links:

Same module references:

xref:other-page.adoc[Link Text]
xref:other-page.adoc#section-id[Link to Section]

Cross-module references:

xref:module:page.adoc[Cross-module Link]
xref:api:authentication.adoc[Authentication Guide]

Cross-component references (with version):

xref:version@component:module:page.adoc[Cross-component Link]
xref:1.0@product:api:rest-api.adoc[REST API v1.0]

Always use xref: syntax for internal documentation links. Never use relative file paths or hardcoded URLs.

For complete Antora configuration details including module creation, navigation structure, and dependency tracking, see the Antora Configuration Guide.

6.2. Antora Attributes

Common Antora attributes available for use in content:

{page-component-title} - Current component title
{page-component-version} - Current version
{page-module} - Current module name
{page-origin-url} - Source file URL

Usage Example:

This page is part of the {page-component-title} component, version {page-component-version}.

7. Accessibility Guidelines

7.1. Alt Text for Images

Always provide descriptive alt text:

image::diagram.svg[Architecture diagram showing three-tier application structure with web, application, and database layers]

7.2. Meaningful Link Text

// Good:
For more information, see the xref:installation.adoc[Installation Guide].

// Avoid:
For more information, click xref:installation.adoc[here].

7.3. Heading Hierarchy

Maintain logical heading hierarchy for screen readers:

= Document Title

== Main Section

=== Subsection

// Don't skip to ==== without ===

7.4. Table Headers

Always use header rows in tables:

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

|Item 1
|Description
|Active
|===

8. PlantUML and Kroki Diagrams

All diagrams MUST use PlantUML syntax.

8.1. PlantUML Block Syntax

[plantuml,diagram-name,svg]
----
@startuml
class Entity {
  +field: Type
  +method(): void
}
@enduml
----

PlantUML Guidelines:

  • Specify diagram name (e.g., diagram-name) for file identification

  • Use svg format for crisp, scalable rendering

  • Keep diagrams focused and readable

  • Use meaningful class and relationship names

  • Add notes for clarification when needed

8.2. Common PlantUML Patterns

Class Diagram:

[plantuml,class-diagram,svg]
----
@startuml
class Parent {
  +parentField: String
}
class Child {
  +childField: Integer
}
Parent <|-- Child
@enduml
----

Sequence Diagram:

[plantuml,sequence-diagram,svg]
----
@startuml
User -> System: Request
System -> Database: Query
Database --> System: Result
System --> User: Response
@enduml
----

Component Diagram:

[plantuml,component-diagram,svg]
----
@startuml
[Web App] --> [API Server]
[API Server] --> [Database]
@enduml
----

State Diagram:

[plantuml,state-diagram,svg]
----
@startuml
hide empty description
[*] --> State1
State1 --> [*]
State1 : this is a string
State1 : this is another string

State1 -> State2
State2 --> [*]
@enduml
----

9. Style Conventions

9.1. Writing Style

  • Use clear, concise language

  • Write in active voice when possible

  • Use present tense for current functionality

  • Use future tense only for planned features

  • Avoid jargon unless necessary (define terms on first use)

  • Use second person ("you") for instructions

  • Use first person plural ("we") sparingly for inclusive statements

Examples:

Active vs Passive Voice
Good: The system validates the input.
Avoid: The input is validated by the system.
Present vs Other Tenses
Good: The function returns a string.
Avoid: The function will return a string.

9.2. Terminology Consistency

  • Define acronyms on first use: "Application Programming Interface (API)"

  • Use consistent terms throughout documentation

  • Maintain a glossary for project-specific terms

  • Use standard technical terms (don’t invent new ones)

9.3. Lists and Instructions

  • Use numbered lists for sequential steps

  • Use bulleted lists for non-sequential items

  • Keep list items parallel in structure

  • Use complete sentences or consistent fragments

Example:

To install the application:

. Download the installer
. Run the installer with administrator privileges
. Follow the on-screen instructions
. Restart your computer

10. Antora Build Considerations

This section covers AsciiDoc patterns that cause issues when building with Antora. Following these guidelines ensures clean builds without warnings or errors.

10.1. Numbered List Best Practices

Always use auto-numbered lists (.) instead of explicit numbers (1., 2., etc.).

When numbered lists are interrupted by code blocks, paragraphs, or section headers, AsciiDoc restarts the numbering. This causes Antora build warnings like:

list item index: expected 1, got 5

10.1.1. Problem: Explicit Numbers with Interruptions

Explicit numbers cause issues when lists are interrupted:

1. First step
2. Second step displays output:
```
Some output here
```
3. Third step  <!-- Warning: expected 1, got 3 -->

10.1.2. Solution: Auto-Numbered Lists with Continuation

Use . for auto-numbering and + for list continuation:

. First step
. Second step displays output:
+

Some output here

. Third step continues correctly

10.1.3. Using [start=N] for Section Breaks

When steps span multiple workflow sections, use [start=N]:

**Step 1: Setup**

. Download the package
. Extract files
. Configure settings

**Step 2: Installation**

[start=4]
. Run the installer
. Accept the license
. Complete setup

10.1.4. Nested Items in Numbered Lists

For sub-items within numbered lists, use * (not with indentation):

. Main step with sub-items:
** Sub-item one
** Sub-item two
** Sub-item three
. Next main step

10.2. Escaping URL Path Parameters

Curly braces in URLs are interpreted as AsciiDoc attribute references.

Path parameters like {id}, {userId}, or {eventId} in REST API documentation will cause warnings:

skipping reference to missing attribute: id

10.2.1. Solution: Define Escape Attributes

Add attribute definitions at the top of documents containing URL path parameters:

= API Documentation
:description: REST API reference
:sectnums:
// Prevent attribute substitution in URL path parameters
:id: \{id\}
:userId: \{userId\}
:type: \{type\}
:eventId: \{eventId\}

== Endpoints

GET `/api/users/{id}` - Returns user by ID
GET `/api/events/{eventId}/participants` - Returns participants

10.2.2. Common Attributes to Define

For REST API documentation, commonly needed escapes include:

// Common path parameter escapes
:id: \{id\}
:type: \{type\}
:key: \{key\}
:userId: \{userId\}
:eventId: \{eventId\}
:processId: \{processId\}
:orgId: \{orgId\}

10.3. Cross-Component References

When referencing pages in other Antora components, use the full cross-component syntax:

// Same component, different module
xref:module:page.adoc[Link Text]

// Different component (REQUIRED: include component name)
xref:component:module:page.adoc[Link Text]

// Example: Reference from registration-portal to event component
xref:event:domain-entities:index.adoc[Domain Entities]

Common mistake: Using module-only syntax for cross-component references:

// WRONG - missing component name
xref:domain-entities:index.adoc[Domain Entities]

// CORRECT - includes component name
xref:event:domain-entities:index.adoc[Domain Entities]

This causes build errors:

target of xref not found: domain-entities:index.adoc

10.4. Code Block Delimiters

Use AsciiDoc listing blocks (----), not Markdown fenced code blocks (` ` `).

Markdown-style blocks cause issues with list continuation and may render inconsistently.

10.4.1. Correct: AsciiDoc Listing Blocks

[source,json]
----
{
  "name": "example",
  "value": 123
}
----

10.4.2. Avoid: Markdown Fenced Blocks

```json
{
  "name": "example",
  "value": 123
}
```

11. Quality Checklist

Use the AsciiDoc Linter to automatically check for common issues before committing.

Before finalizing any AsciiDoc document, verify:

Document Structure:

  • Page title is clear and descriptive

  • Description and keywords attributes are present

  • Heading hierarchy is correct (no skipped levels)

Lists and Code:

  • Numbered lists use . (auto-numbering), not explicit numbers

  • Code blocks use ---- delimiters, not Markdown ` ` `

  • List continuations use + after code blocks

  • Code blocks have language specification

Links and References:

  • All cross-references use xref: syntax

  • Cross-component references include component name (component:module:page.adoc)

  • No hardcoded URLs (use xrefs or Antora attributes)

  • Links open in appropriate target (same/new window)

API Documentation:

  • URL path parameters ({id}, {type}) are escaped with attribute definitions

  • REST endpoints display correctly without attribute warnings

Content Quality:

  • Images have descriptive alt text

  • Tables use proper column specifications and have headers

  • Admonitions are used appropriately

  • File names use lowercase-with-hyphens

  • Content is accessible (alt text, meaningful links, heading hierarchy)

  • Spelling and grammar are correct

  • Technical accuracy is verified

12. Common Pitfalls to Avoid

DO NOT:

Syntax and Formatting:

  • Use Markdown syntax (use AsciiDoc) - especially ` ` ` code fences

  • Use explicit numbered lists (1., 2.) - use . for auto-numbering

  • Skip heading levels (e.g., == to ====)

  • Use relative file paths (use Antora xrefs)

  • Use HTML in content (use AsciiDoc markup)

  • Mix tab and space indentation

  • Leave trailing whitespace

References and Links:

  • Use module-only syntax for cross-component references (include component name)

  • Omit component name in xref: when linking to different components

  • Use "click here" as link text

API Documentation:

  • Leave {id}, {type} etc. unescaped in REST endpoints

  • Assume curly braces in URLs will render correctly

Content Quality:

  • Omit alt text for images

  • Overuse formatting (bold, italic, etc.)

  • Use inconsistent terminology

For Antora-specific pitfalls (forgetting to register modules, navigation structure issues, etc.), see the Common Pitfalls section in the Antora Configuration Guide.

13. Troubleshooting

13.1. Common Rendering Issues

Issue: Cross-references not working

  • Verify xref syntax: Link Text

  • Check that target file exists in correct module/component

  • Ensure file extension is included (.adoc)

Issue: Images not displaying

  • Verify image file is in images/ directory

  • Check image reference syntax: image::filename.png[Alt Text]

  • Ensure image file name matches exactly (case-sensitive)

Issue: Code blocks not highlighting

  • Verify language identifier: [source,java]

  • Check that language is supported

  • Ensure code block uses correct delimiter (----)

Issue: PlantUML diagrams not rendering

  • Verify Kroki integration is configured

  • Check PlantUML syntax is valid

  • Ensure diagram name and format are specified

14. Additional Resources

This style guide ensures consistent, high-quality AsciiDoc documentation.