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. The block title must only occupy a single line and thus cannot be wrapped.

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        main   -> 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        main   -> 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:16-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:16-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.

Captioned titles

Several block contexts support captioned titles. A captioned title is a title that’s prefixed with a caption label and a number followed by a dot (e.g., Table 1. Properties).

The captioned title is only used if the corresponding caption attribute is set. Otherwise, the original title is displayed.

The following table lists the blocks that support captioned titles and the attributes that the converter uses to generate and control them.

Blocks that support captioned titles
Block context Caption attribute Counter attribute

appendix

appendix-caption

appendix-number

example

example-caption

example-number

image

figure-caption

figure-number

listing, source

listing-caption

listing-number

table

table-caption

table-number

All caption attributes are set by default except for the attribute for listing and source blocks (listing-caption). The number is sequential, computed automatically, and stored in a corresponding counter attribute.

Let’s assume you’ve added a title to an example block as follows:

.Block that supports captioned title
====
Block content
====

The block title will be displayed with a caption label and number, as shown here:

Example 1. Block that supports captioned title

Block content

If you unset the example-caption attribute, the caption will not be prepended to the title.

Block that supports captioned title

Block content

The counter attribute (e.g., example-number) can be used to influence the start number for the first block with that context or the next number selected in the sequence for subsequent occurrences. However, this practice should be used judiciously.

The caption can be overridden using the caption attribute on the block. The value of the caption attribute replaces the entire caption, including the space that precedes the title.

Here’s how to define a custom caption on a block:

.Block Title
[caption="Example {counter:my-example-number:A}: "]
====
Block content
====

Here’s how the block will be displayed with the custom caption:

Example A: Block Title

Block content

Notice we’ve used a counter attribute in the value of the caption attribute to create a custom number sequence.

If you refer to a block with a custom caption using an xref, you may not get the result that you expect. Therefore, it’s always best to define custom xreftext when you define a custom caption.