Skip to main content

Getting started with AsciiDoc syntax

Author: Joseph Cayouette
Version: v1.0 (2025-10-22)

Overview​

This guide introduces the most common AsciiDoc syntax and conventions used in SUSE technical documentation.
You’ll also learn how to structure content effectively, and apply best practices for maintainable writing.

SUSE Documentation Style Guide (Asciidoc)​

Syntax​

Processing​

Getting Started with AsciiDoc Syntax

AsciiDoc is a lightweight, text-based markup language for authoring documentation, books, and technical content.
It’s readable in plain text and easily converts to HTML, PDF, and other formats through Asciidoctor.

This guide provides a full syntax overview and examples for each feature of AsciiDoc.

Table of contents​

Paragraphs​

A paragraph is one or more consecutive lines of text. Blank lines separate paragraphs.

This is a normal paragraph.

This is another paragraph.

For literal paragraphs (preserve formatting):

  This is a literal paragraph.
  Leading spaces and newlines are preserved.

Text formatting​

AsciiDoc supports rich inline formatting:

*bold* _italic_ *_bold italic_* `monospace`
^superscript^ ~subscript~

Result: bold, italic, bold italic, monospace, superscript^text^, subscripttext.

https://asciidoctor.org
https://asciidoctor.org[AsciiDoctor]
mailto:user@example.com[Email Us]
link:../file.adoc[Relative Link]

Document header​

The header defines metadata and attributes.

= Document Title
Author Name <author@example.com>
v1.0, 2025-10-22
:toc:
:sectnums:

Section titles​

= Level 0 Title
== Level 1
=== Level 2
==== Level 3
===== Level 4
====== Level 5

Automatic TOC​

Enable a table of contents automatically with:

:toc:
:toclevels: 3

The TOC appears in the rendered output.

Includes​

Include other files or snippets:

include::chapter1.adoc[]
include::snippets/code-example.adoc[tag=main]

Lists​

Unordered list​

* Item 1
** Sub-item
*** Sub-sub-item

Ordered list​

. Step 1
. Step 2
.. Sub-step

Description list​

Term 1:: Definition
Term 2::
Multi-line definition

Checklist​

* [x] Done
* [ ] Not done

Images​

image::example.png[Alt text,300,200]
image::https://asciidoctor.org/images/octocat.jpg[GitHub mascot]

Use :imagesdir: to set a base directory.

Audio​

audio::track.mp3[]
audio::https://example.com/music.mp3[Sample Audio]

Videos​

video::sample.mp4[width=640, height=360]
video::https://www.youtube.com/embed/abcd1234[youtube]

Keyboard, Button, and Menu Macros​

kbd:[Ctrl+S]
btn:[Submit]
menu:File[Save As]

Literals and Source Code​

Inline Literal​

Use `+command+` to mark literal text.

Source Block​

[source,python]
----
print("Hello, AsciiDoc!")
----

Callouts​

[source,python]
----
print("Hello") # <1>
print("World!") # <2>
----
<1> Prints hello
<2> Prints world

Admonitions​

NOTE: This is a note.
TIP: Pro tip here.
IMPORTANT: Don’t skip this.
WARNING: Be cautious!
CAUTION: Handle carefully.

Block style:

[WARNING]
====
Critical warning block.
====

More Delimited Blocks​

.Example
====
This is an example block.
====

.Quote
____
“Knowledge speaks, but wisdom listens.”
____

.Sidebar
****
Additional context or tips.
****

.Literal Block
....
$ echo "Hello"
....

Tables​

|===
| Name | Age | Role
| Alice | 30 | Developer
| Bob | 40 | Manager
|===

IDs, Roles, and Options​

[#custom-id]
== Section Title

[.role-name]
Text styled with role.

[options="header"]
|===
| Header | Value
| One | 1
| Two | 2
|===

Comments​

Comments are ignored in the output:

// This is a comment line
////
This is a comment block.
Ignored in output.
////

Breaks​

Line break +++
New line continues.

Horizontal rule:

''' or ---

Attributes and Substitutions​

:project-name: MyApp

The project name is {project-name}.

Substitutions apply within inline content or blocks using [subs=+].

Text Replacements​

Define replacements globally:

:heart: ❤️

I {heart} AsciiDoc!

Escaping Substitutions​

To prevent AsciiDoc from processing text, use a backslash or pass macro:

\*Not bold\*
pass:[*Not bold*]

Bibliography​

[bibliography]
== References

* [[[iso9001]]] ISO 9001:2015 Quality Management
* [[[agile]]] Manifesto for Agile Software Development

Reference example:

See <<iso9001>> for details.

Footnotes​

A sentence with a footnote.footnote:[This is the footnote text.]

Markdown Compatibility​

AsciiDoc supports most Markdown-style syntax:

*italic* or _italic_
**bold** or __bold__
`code` or ``code``

However, AsciiDoc syntax is more structured and extensible.

Last updated: October 2025