Add a Title to a Block

You can assign a title to a block, whether it’s styled using its style name or delimiters.

Block title syntax

A block title is defined on its own line directly above the block’s attribute list, opening delimiter, or block content—which ever comes first. As shown in Example 1, the line must begin with a dot (.) and immediately be followed by the text of the title.

Example 1. Block title syntax

.This is the title of a sidebar block
****
This is the content of the sidebar block.
****

The next sections will show how to add titles to delimited blocks and blocks with attribute lists.

Add a title to a delimited block

Any delimited block can have a title. If the block doesn’t have an attribute list, enter the title on a new line directly above the opening delimiter. The delimited literal block in Example 2 is titled Terminal Output.

Example 2. Add a title to a delimited block

.Terminal Output (1)
.... (2)
From github.com:asciidoctor/asciidoctor
 * branch        master   -> FETCH_HEAD
Already up to date.
....

1	The block title is entered on a new line. The title must begin with a dot (`.`). Don’t put a space between the dot and the first character of the title.
2	If you aren’t applying attributes to a block, enter the opening delimiter on a new line directly after the title.

The result of Example 2 is displayed below.

Terminal Output

From github.com:asciidoctor/asciidoctor
 * branch        master   -> FETCH_HEAD
Already up to date.

In the next section, you’ll see how a title is placed on a block that has an attribute list.

Add a title to a block with attributes

When you’re applying attributes to a block, the title is placed on the line above the attribute list (or lists). Example 3 shows a delimited source code block that’s titled Specify GitLab CI stages.

Example 3. Add a title to a delimited source code block

.Specify GitLab CI stages (1)
[source,yaml] (2)
----
image: node:10.16.3-buster
stages: [ init, verify, deploy ]
----

1	The block title is entered on a new line.
2	The block’s attribute list is entered on a new line directly after the title.

The result of Example 3 is displayed below.

Specify GitLab CI stages

image: node:10.16.3-buster
stages: [ init, verify, deploy ]

As shown in Example 4, a block’s title is placed above the attribute list when a block isn’t delimited.

Example 4. Add a title to a non-delimited block

.Mint
[sidebar]
Mint has visions of global conquest.
If you don't plant it in a container, it will take over your garden.

The result of Example 4 is displayed below.

Mint

Mint has visions of global conquest. If you don’t plant it in a container, it will take over your garden.

You may notice that unlike the titles in the previous rendered listing and source block examples, the sidebar’s title is centered and displayed inside the sidebar’s background. How the title of a block is displayed depends on the converter and stylesheet you’re applying to your AsciiDoc documents.