Asciidoc

Tags:
Categories:

Syntax

Since AsciiDoc is offered as a “complete system,” including both language and interpreter, there is a central syntax. Unlike Markdown, AsciiDoc has no variants or dialects.

Comments

AsciiDoc code can be commented, just like any other source code. This means that comments are not taken into account during the interpretation of the source text (e.g., when converting to PDF). This allows documents or parts of text to be commented on, or notes to be left.


This is arbitrary text in AsciiDoc.

// This line will not be interpreted.

This line will be displayed.

Paragraphs/Lines

AsciiDoc does not require special specifications for line breaks and paragraphs. The text is rendered as it was written. However, it is possible to force a line break using a plus symbol. Alternatively, the attribute [%hardbreaks] can be prepended.


This is line number one.
This is line number two.

And now another paragraph.

This line will be +
hard broken.

[%hardbreaks]
These lines will be 
displayed as they are.

Text Formatting

Bold, Italic, Highlight, Code

To display text as bold, italic, or code, there are two possibilities, depending on whether the text to be formatted stands alone or is located in the middle of a text.

A single word can be enclosed in single asterisks, underscores, hashtags, or grave accents.


This text is *bold*.
This text is _italic_.
This text is `code`.
This text is #highlighted#.

If you want to format a part of text in the middle of a sentence, this is achieved by using double asterisks, underscores, hashtags, or grave accents. If this were attempted with single characters, the formatting rule would be ignored.


The "tt" in Mi**tt**ag are bold.
The "tt" in Mi*tt*ag are not bold.

The "tt" in Mi__tt__ag are italic.
The "tt" in Mi_tt_ag are not italic.

The "tt" in Mi``tt``ag are code.
The "tt" in Mi`tt`ag are not code.

The "tt" in Mi##tt##ag are highlighted.
The "tt" in Mi#tt#ag are not highlighted.

Underlined, Strikethrough

To underline or strikethrough text, hashtags with an attribute are used.


This text is [.underline]#underlined#.
This text is [.line-through]#strikethrough#.

Superscript, Subscript, and Smart Quotes

Using superscript and subscript, parts of text can be raised or lowered. For this, the text parts are placed between single carets/circumflexes (superscript) or tildes (subscript).


This is a ~low~point.
This is a ^high^point.

Here is the completed AsciiDoc text with content for the empty chapters (starting from “Links”), based on the official AsciiDoc syntax and common best practices:

Here is the revised version of your AsciiDoc documentation — now with a short, concise explanation for each chapter before the syntax examples come. This keeps it clear, understandable, and useful for beginners.

Explanation:
AsciiDoc supports both external web links and internal references within the document (anchors) as well as links to local files. The syntax is simple and intuitive — ideal for documentation that needs to be linked.

https://www.asciidoc.org[AsciiDoc Website]

[[section1]]
== First Section

See also <<section1>>.

link:manual.pdf[Download Manual]

Document Header

Explanation:
The document header contains metadata such as title, author, date, and global attributes. It is optional but recommended for structured documents — especially for PDF or book exports.

= Document Title
Author Name <author@example.com>
:doctype: book
:author: Author Name
:revdate: 2026-02-09

Automatic Table of Contents

Explanation:
A table of contents (TOC) is automatically generated as soon as the attribute :toc: is set. It can be placed on the left, right, or anywhere else — helpful for longer documents.

:toc: left

= Main Title

== Chapter 1
Content...

== Chapter 2
Further content...

Includes

Explanation:
With include::, you can embed external AsciiDoc files or parts of them. Practical for reusable sections (e.g., footnotes, notes, chapters).

include::chapter1.adoc[]

include::../shared/footnotes.adoc[tag=section2]

Lists

Explanation:
AsciiDoc supports bulleted lists (*), numbered lists (.), and definition lists (::). Indentation determines the hierarchy — simple and clearly structured.

Bulleted Lists

* Point 1
* Point 2
  * Subpoint

Numbered Lists

. First point
. Second point
.. Subpoint

Definitions

Term::
  Definition of the term.

Images

Explanation:
Images are embedded using image::. You can control size, alt text, and scaling. Works in HTML, PDF, and EPUB — depending on the backend.

image::logo.png[Logo, 200, 100]

image::diagram.svg[Diagram, scaledwidth=50%]

Audio

Explanation:
Audio files (e.g., voice messages) can be embedded directly in the document. Useful for tutorials or multimedia documentation.

audio::voicemessage.mp3[Voice Message, autoplay]

Videos

Explanation:
Videos are embedded using video::. You can enable controls like autoplay, controls, or loop — ideal for instructions or presentations.

video::tutorial.mp4[Tutorial, width=640, height=360, autoplay, controls]

Keyboard, Button, Menu Macros

Explanation:
With kbd: and menu:, you can clearly highlight keyboard shortcuts and menu paths — particularly useful in instructions or software documentation.

Keyboard Shortcuts

Press kbd:[Ctrl+C] to copy.

Go to menu:File[Save As...].

Source Code

Explanation:
Code blocks with syntax highlighting are introduced with [source]. You can specify languages like Python, Bash, or HTML — helpful for developer documentation.

[source,python]
----
def hello():
    print("Hello World")
----

Notes, Text Blocks

Explanation:
With NOTE:, TIP:, WARNING:, etc., you can highlight important information. Quotes with ____ are ideal for quotations or excerpts from external sources.

Notes

NOTE: This is important information.

TIP: Here's how to do it faster.

Quotes

____
"This is a quote."
— Author
____

Tables

Explanation:
Tables are defined with |===. Each cell is separated by |. You can control column count, borders, and captions — perfect for comparisons or data.

|===
| Column 1 | Column 2
| Value A  | Value B
| Value C  | Value D
|===

IDs, Roles, and Options

Explanation:
With [[id]], you set anchors for internal links. With [.role], you can assign CSS classes. With [%option], you control block behavior (e.g., unnumbered).

IDs

[[chapter2]]
== Chapter 2

Roles

[.note]
This text has a role.

Options

[%unnumbered]
== This section has no number.

Attributes and Special Characters

Explanation:
Attributes (:name: value) enable reuse of text or values. Special characters like + or \\ may need to be escaped to avoid being interpreted as formatting.

Attributes

:version: 1.0

The version is {version}.

Special Characters

+ for plus, \\ for backslash, &#x27; for apostrophe.

Bibliography

Explanation:
A bibliography can be created manually or via bibliography::. Useful for scientific or referenced documents.

[bibliography]
== Literature

- Author, Title, Publisher, Year

Footnotes

Explanation:
Footnotes are inserted with footnote:[Text] or [footnote:]. They appear at the end of the document or page — ideal for supplementary information.

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

Another sentence with [footnote:2]Footnote 2[footnote:2].

Conclusion

Advantages

A major advantage of AsciiDoc is certainly its wide range of functions, which even allows complex documents with tables of contents and bibliographies. The include function and possible comments also facilitate handling large amounts of text and many files; collaborative editing is thus also easy. Since AsciiDoc is not just a language but also comes with an application, productive work can be done without much detour. Apart from a text editor for the text files, nothing else is needed.

Disadvantages

AsciiDoc is by far not as widely used as Markdown. Productive tools like note-taking apps, wikis, or static site generators rarely support AsciiDoc, and if they do, usually only via plugins. Those who work a lot with such tools will not get around using Markdown and AsciiDoc in parallel.

Further Information

Literature

Tools for Using AsciiDoc

Text Editors

Static Site Generators

Transformation Tools