.ADOC File Format – Blocks, lists and tables

AsciiDoc

The body of an AsciiDoc document is a sequence of blocks: paragraphs, delimited blocks, lists, tables, images and breaks. Any block may be preceded by lines that give it a title, an ID and attributes.

Block metadata

LineMeaning
.Title textThe block’s title: a dot followed straight away by the text, with no space.
[style#id.role1.role2%option,attr=value,positional]The block attribute list. The first positional attribute is the style, followed by shorthand entries in any order: # an ID, . a role (CSS class), % an option. Named and further positional attributes follow. Values may be quoted.
[[id,xreftext]]The legacy anchor syntax for a block ID, with optional cross-reference text.

Delimited blocks

A delimited block runs from an opening delimiter line to a closing line that matches it exactly in characters and length. Delimiters are at least four characters long, except the open block’s, which is always two. To nest a block of the same type, the inner one uses a different length (longer or shorter).

DelimiterBlockContent
----ListingVerbatim; with [source,lang] it is a source block, highlighted. [literal] turns it into a literal block.
....LiteralVerbatim, no highlighting; [listing] or [source] turns it into a listing.
====ExampleAny blocks; with NOTE, TIP, IMPORTANT, CAUTION or WARNING as its style it becomes an admonition block.
****SidebarAny blocks, set aside.
____QuoteAny blocks; [quote,attribution,citation] or [verse,attribution,citation] sets the style.
--OpenAny blocks; can take any block style except pass and table, and cannot hold another open block.
++++PassthroughRaw content passed to the output (raw HTML, for example); [stem], [latexmath] or [asciimath] make it maths.
|===, ,===, :===, !===TableSee tables.
////CommentNot output.
```Listing (Markdown style)Fenced code with syntax highlighting; an optional Markdown-compatible feature, so far only in Asciidoctor.

Paragraphs can take the same styles as an open block without delimiters: [abstract], the admonition labels, [comment], [example], [literal], [listing] or [source,python], [partintro], [pass], [quote], [sidebar] and [verse], plus [normal], which turns a literal paragraph back into a normal one. A paragraph whose first line is indented by one or more spaces is a literal paragraph.

Verbatim blocks may contain callouts: <1> at the end of a line, explained by a callout list (<1> Explanation) after the block. Each number appears twice, once in the block and once in the list. A callout can hide behind a line comment of the language (// <1>, # <1>).

Admonitions

Five types: NOTE, TIP, IMPORTANT, CAUTION and WARNING. As a paragraph: NOTE: text. As a block: [NOTE] above an example block (====) holding any content.

Images, audio and video

MacroAttributes
image::path[alt,width,height]alt, width, height, id, title, caption, fallback, format, align (left, center, right), float (left, right), link, window, scale, scaledwidth, pdfwidth, role, opts; paths are relative to imagesdir.
video::path[poster,width,height]poster, width, height, start, end (seconds), title; youtube or vimeo in the first position embeds a video from that service by its ID (YouTube also takes theme, lang, list, playlist); options autoplay, loop, modest, nocontrols, nofullscreen.
audio::path[]start, end, title; options autoplay, loop, controls, nocontrols.
toc::[]Places the table of contents here, once per document, when toc is set to macro; otherwise it is ignored.

Lists

ListMarkersNotes
Unordered*, **, ***…, or - for a single levelA new level starts at each different marker, so by convention the number of asterisks is the level; nesting has no fixed limit. Styles [square], [circle], [disc], [none] or [no-bullet], and [unstyled] set the bullet.
Checklist* [ ], * [x], * [*]Unchecked and checked items; %interactive makes them clickable.
Ordered., .., ...…, or explicit numbers 1. (which must be in sequence)Each level gets its own numbering scheme. Styles [arabic], [decimal] (leading zero), [loweralpha], [upperalpha], [lowerroman], [upperroman], [lowergreek]; attribute start and option %reversed.
Descriptionterm:: description; also :::, :::: and ;; for nestingStyles [horizontal] (term and description side by side), [qanda] (questions and answers, shown as an ordered list) and [glossary] (in a glossary section).
Callout<1>, or <.> for automatic numbersExplains the callouts of the block above.
Bibliography* [[[label]]] Entry in a [bibliography] sectionEntries cited with <<label>>; [[[label,xreftext]]] shows the xreftext instead.

A line with only + attaches the next block to the current list item (list continuation). Adjacent items with the same marker join one list even across empty lines; to start a new list, put a line comment // or a block attribute line between the two, with empty lines around it.

Tables

[cols="1,2a,^1",options="header"]
|===
| Name | Description | Qty
| Box  | A *strong* box. | 3
|===
  • Cells start with the separator, | by default; a cell may be on its own line. If the first line inside the delimiters has content and the second is empty, the first row becomes the header (or use %header). A separator inside a cell is escaped with a backslash.
  • ,=== holds CSV data, :=== DSV (colon-separated) and !=== a table nested inside a cell, whose cells are separated by !. format (psv, csv, tsv, dsv) and separator change the parsing.
  • cols gives one specifier per column: an optional multiplier (3*), alignment (< left, ^ centre, > right, then .<, .^, .> for top, middle, bottom), a width (an integer proportion, a percentage, or ~ for automatic) and a style letter.
  • Style letters: a AsciiDoc (any blocks), d default (paragraph text; used when none is given), e emphasis, h header, l literal, m monospace, s strong.
  • A cell specifier before | spans and styles one cell: 2+| spans two columns, .3+| three rows, 2.3+| both, 3*| repeats the cell three times, and alignment and style letters may follow, as in ^.^a|.
  • Other attributes: options (header, footer, autowidth, breakable, unbreakable, rotate), frame (all, ends, sides, none), grid (all, cols, rows, none), stripes (none, even, odd, hover, all), width (a percentage), align, caption.

Breaks

LineMeaning
'''Thematic break (horizontal rule). Asciidoctor also accepts the Markdown forms ---, - - -, *** and * * *.
<<<Page break: a hint to the converter, used in paged output such as PDF.

Sources