AsciiDoc is a lightweight markup language that lets you convert texts into various document formats. AsciiDoc files can be converted to HTML, PDF, ePub, and other formats.

Compared to XML-based formats such as DocBook, AsciiDoc is easy to learn and remains readable as plain text. More information is available on Wikipedia.

Write your text in the editor as usual. You can write everything continuously or place each sentence on a new line; the output looks the same either way.

Create a new paragraph by inserting a blank line between paragraphs.

This introduces a central AsciiDoc concept: the block.

A block is any contiguous structural unit at block level, not to be confused with a typographic "text block."

Blocks include:

Regular body text is a paragraph block and does not need to be declared explicitly as a block; it is one implicitly.

Design in AsciiDoc comes from Cascading Style Sheets. As in any markup language, you highlight individual words in the editor as bold, italic, or in other ways. The editor menu in adoc Studio provides all important formatting options for quick mouse access.

AsciiDoc can do much more.
Combine different formatting options freely.

Result in preview:

Define headings and their level by the number of = signs. In the source text, all headings look like this:

If the six heading levels plus the document title are not enough, add a paragraph title by placing a . before the line:

The document title, marked with =, defines the document header.

To establish a clear structure from the start, every AsciiDoc document should begin with a document header. It contains:

Although the AsciiDoc documentation recommends placing the title (= Document Title) on the first line, a different structure has proven effective in practice.

In documents with many attributes, such as this manual, all attributes are placed before the document title, not after it.

The output is identical, but the readability improves considerably, particularly with adoc Studio features such as composite documents and translation support.

The advantage is immediately apparent: the document header is clearly structured and much easier to read.

As soon as you use headings, a table of contents is recommended. In adoc Studio, add :toc: to the document header. adoc Studio generates the table of contents automatically.

By default:

The :toc: attribute supports additional parameters:

The number after :toclevels: specifies how many heading levels the table of contents should display, for example :toclevels: 3.

Define this attribute in the document header. By default, the table of contents shows two levels.

You can use two types of links:

The introduction explains how images and their paths work. This section describes how to embed images directly in AsciiDoc text.

Images can be inserted in two ways: as a block image or as an inline image in body text.

Start an unordered list with a *:

Each additional asterisk indents one level deeper:

Alternatively, use -:

Create ordered lists with a period .:

You can also specify numbers:

The same principle as for unordered lists applies to nested ordered lists:

Which numbering style is used at a given level depends on the product style.

Checklists are also supported:

Set the attribute :icons: font beforehand so that checklists are rendered according to the product style.

Block elements (blocks for short) are versatile in AsciiDoc. There are numerous use cases and display forms.

Typical applications include:

Blocks can be written in different forms:

The following examples demonstrate the concept using a quote.

Quote (short form)

Write a quote in short form:

Quote (as paragraph)

Write a quote as a paragraph:

Quote (multiple paragraphs)

For a quote spanning multiple paragraphs, use block delimiters:

A block always sits between two delimiters, each consisting of four identical characters. These mark the start and end of the block.

There are different possible delimiters, as shown in the following example:

Use tables to present content in a structured way. Even a few characters are enough for a tabular layout.

Start with a minimal table:

The result:

Add more rows to a table:

The result:

Create a header row by inserting a blank line after the first row:

The result:

AsciiDoc provides extensive options for formatting table cells. The following example is based on the official documentation:

The result:

In technical documentation, describing the graphical user interface (GUI, abbreviated UI for User Interface) is a daily task.

Three areas play a central role:

Use the kbd:[] macro to display keyboard shortcuts.

Example → ⌘+S saves the document quickly.

A special feature of the kbd:[] macro is visible in the use of the arrow keys (↑ ↓ ← →) in this document.

Use the menu:[] macro to display menu paths, for example:

File  Export  Products…

The btn:[] macro is available for buttons.

This renders a button such as OK.

On the Apple platform in particular, using SF Symbols with the UI macros is especially useful, as it allows system elements to be represented authentically and in a platform-consistent way.

Comments in the source text are used to add notes, remarks, or tasks directly in the document. They help explain background, document decisions, or make thought processes traceable. Comments are visible only in the editor. They do not appear in the preview or in exports.

Start a line with // to mark the following text as a comment:

To comment out larger sections of text, use //// at the beginning and end of the block:

Even though comments do not appear in the finished document, they are very useful when working in the source text. Typical uses are::

Attributes make your documentation more flexible and reusable.

In adoc Studio, attributes serve several purposes. They allow you to:

Conditions control whether text is output or not in adoc Studio. Think of directives as programmatic control commands within the document that influence behavior without appearing in the final document themselves.

Available directives:

During processing, the processor checks the condition based on existing attributes or their values. If the condition is true, the text is output; otherwise it is skipped.

AsciiDoc supports working with multiple files. Instead of creating one long file, divide the text into individual chapters.

In adoc Studio, the section The Project Navigator introduced a dedicated concept for modular documents.

When authors do not use all adoc Studio features, the include directive is a good option. It lets you include chapters in AsciiDoc format one after another:

Within adoc Studio, the include directive is particularly useful when not all features are documented immediately. Placeholders can be used for this purpose. Example: In the file list there is a file comingSoon.adoc. To keep it from appearing automatically in the composite document, the corresponding checkbox was disabled in the file information. More details are here.

Include the placeholder file as follows:

The output looks like this:

Content of the placeholder file:

Explanation:

With Docinfo, you insert custom content into the head or footer of the output document. The converter reads this content from so-called docinfo files. Docinfo files extend the automatically generated output and offer practical ways to add extra metadata, stylesheets, or scripts that the converter does not provide by default.

In adoc Studio, do not set the :docinfo: attribute directly in the document. Unlike Asciidoctor, adoc Studio shows not only HTML but also PDF in the preview. Because PDF is based on HTML, adoc Studio interprets the attribute correctly, but the output can look visually disruptive. To avoid this, two options are available: