Blocks

Title

You can assign a title to any paragraph, list, delimited block, or block macro. In most cases, the title is displayed immediately above the content. If the content is a figure or image, the title is displayed below the content.

A block title is defined on a line above the element. The line must begin with a dot (.) and be followed immediately by the title text.

Here’s an example of a list with a title:

.TODO list
- Learn the AsciiDoc syntax
- Install Asciidoctor
- Write my document

Metadata

In addition to a title, a block can be assigned additional metadata including:

  • ID (anchor)

  • Block name (first positional attribute)

  • Block attributes

Here’s an example of a quote block with metadata:

.Gettysburg Address (1)
[#gettysburg] (2)
[quote, Abraham Lincoln, Address delivered at the dedication of the Cemetery at Gettysburg] (3) (4) (5)
____
Four score and seven years ago our fathers brought forth
on this continent a new nation...

Now we are engaged in a great civil war, testing whether
that nation, or any nation so conceived and so dedicated,
can long endure. ...
____
1 Title: Gettysburg Address
2 ID: gettysburg
3 Block name: quote
4 attribution: Abraham Lincoln (Named block attribute)
5 citetitle: Address delivered at the dedication of the Cemetery at Gettysburg (Named block attribute)
A block can have multiple block attribute lines. The attributes will be aggregated. If there is a name conflict, the last attribute defined wins.

Some metadata is used as supplementary content, such as the title, whereas other metadata controls how the block is converted, such as the block name.

Delimited blocks

The AsciiDoc syntax provides a set of components for including non-paragraph text, such as block quotes, source code listings, sidebars and tables, in your document. These components are referred to as delimited blocks because they are surrounded by delimiter lines (e.g., ****).

Here’s an example of a sidebar block:

****
sidebar block
****

Within the boundaries of a delimited block, you can enter any content or blank lines. The block doesn’t end until the ending delimiter is found. The delimiters around the block determine the type of block, how the content is processed and converted, and what elements are used to wrap the content in the output.

Delimiter lines

The boundaries of a delimited block must be balanced. In other words, the opening delimiter line must be the same length as the closing delimiter line.

For example, the following delimited block is not balanced and therefore invalid:

********
invalid sidebar block
****

When the processor encounters the previous example, it will put the remainder of the content in the document inside the delimited block (without warning, currently). As far as the processor is concerned, the closing delimiter is just a line of content. If you want the closing delimiter to be matched, it must be the same length as the opening delimiter.

****
valid sidebar block
****

The AsciiDoc Python processor did not require the delimiters to be balanced, but also never documented that this was permissible. We view AsciiDoc Python’s behavior of matching unbalanced delimited blocks to be a bug and therefore do not allow it in Asciidoctor.

Optional delimiters

If the content is contiguous (not interrupted by blank lines), you can forgo the use of the block delimiters and instead use the block name above a paragraph to repurpose it as one of the delimited block types.

This format is often used for single-line listings:

[listing]
sudo dnf install asciidoc

or single-line quotes:

[quote]
Never do today what you can put off `'til tomorrow.

Masquerading blocks

Some blocks can masquerade as other blocks, a feature which is controlled by the block name.

Nesting blocks

You can nest blocks inside each other. To nest blocks of the same type, add a pair of extra symbols to the delimiter. For example:

====
This is an example
======
This is an example inside an example
======
====

Built-in blocks summary

The following table identifies the built-in block names and delimited blocks syntax, their purposes, and the substitutions performed on their contents.

Block Block Name Delimiter Purpose Substitutions

Admonition

[<LABEL>]

Any delimiter

Content labeled with a tag or icon, can masquerade as any delimited block type

Varies

Comment

N/A

////

Private notes that are not displayed in the output

None

Example

[example]

====

Designates example content or defines an admonition block

Normal

Fenced

N/A

```

Source code or keyboard input is displayed as entered

Verbatim

Listing

[listing]

----

Source code or keyboard input is displayed as entered

Verbatim

Literal

[literal]

....

Output text is displayed exactly as entered

Verbatim

Open

Most block names

--

Anonymous block that can act as any block except passthrough or table blocks

Varies

Passthrough

[pass]

++++

Unprocessed content that is sent directly to the output

None

Quote

[quote]

____

A quotation with optional attribution

Normal

Sidebar

[sidebar]

****

Aside text and content displayed outside the flow of the document

Normal

Source

[source]

----

Source code or keyboard input to be displayed as entered

Verbatim

Stem

[stem]

++++

Unprocessed content that is sent directly to an interpreter (such as AsciiMath or LaTeX math)

None

Table

N/A

|===

Displays tabular content

Varies

Verse

[verse]

____

A verse with optional attribution

Normal

This table shows the substitutions performed by each substitution group referenced in the previous table.

Substitution groups
Group Special characters Quotes Attributes Replacements Macros Post replacements

Header

Yes

No

Yes

No

No

No

None

No

No

No

No

No

No

Normal

Yes

Yes

Yes

Yes

Yes

Yes

Pass

No

No

No

No

No

No

Verbatim

Yes

No

No

No

No

No

Surround an attribute value with single quotes in order to apply normal substitutions.