Key Concepts

A document represents the top-level block element in AsciiDoc. It consists of an optional document header and either a) one or more sections preceded by an optional preamble or b) a sequence of top-level blocks only.

The document can be configured using a document header. The header is not a block itself, but contributes metadata to the document, such as the document title and document attributes.

An element is an identifiable, addressable, and composable chunk of content in a document. An AsciiDoc document is merely a composition of all the elements it contains.

Elements are a hierarchy of types, where one element may be a specialization of a family of elements. For example, a sidebar block is a block element, so it shares the traits of all block elements, and also adds some of its own.

Elements include the document itself, sections, blocks, block macros, breaks, and inline phrases and macros.

A block element is stacked vertically (by line) above or below other block elements. Block elements are typically referred to simply as blocks. Blocks form the main tree structure of the document.

An inline element is a span of content within a block element or one of its attributes (e.g., a block title). Inline elements include formatted text (italic, bold, etc), inline macros, and element references. What fills in the gap between these elements is unsubstituted text. Inline elements are less structured than block elements as they are more geared towards substitutions than a tree structure.

An attribute is a name/value pair used for storing and disclosing metadata in the AsciiDoc language. Attributes can be used to influence the syntax, control behavior, customize styles, activate or configure integrations, or store inline replacement content. Attributes truly set AsciiDoc apart from other lightweight markup languages.

An attribute is actually an abstract term. There are two concrete classifications of attributes: document attributes and element attributes.

As you read through this documentation, you’ll frequently see references to the term macro. A macro is a syntax for representing non-text elements or syntax that expands into text using the provided metadata. See macro to learn more about the meaning of this term.

Here’s an example of a block macro:

Here’s an example of an inline macro:

You can think of a macro like a function. A syntax of macro follows the form of a name, a target which is sometimes optional, and an attribute list consisting of zero or more element attributes enclosed in square brackets.

There are two variations of a macro: block and inline. In a block macro, the name and target are separated by two colons (::) and it must reside on a line by itself. In an inline macro, the name and target are separated by a single colon (:) and it can be alongside text and other inline elements. A block macro is always parsed, whereas an inline macro is only parsed where the macros substitution is enabled.

There’s another syntax in AsciiDoc that looks a lot like block macros, only they aren’t. These are the preprocessor directives.

A preprocessor directive is a function that controls lines that are fed into the parser. A conditional preprocessor directive can configure lines to be included or excluded based on the presence of an attribute (ifdef, ifndef) or another arbitrary condition (ifeval). An include directive can add additional lines to the document taken from another document.

Preprocessor directives share common traits with a block macro. Like a block macro, a preprocessor directive must be on a line by itself. While the preprocessor directive can access document attributes, it’s not otherwise aware of the context around it. It’s only a line processor. Like a block macro, the include directive can have element attributes, though they only apply to the preprocessing operation itself.