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.
.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.
.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.
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.
.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.
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.
.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.
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.
Block context | Caption attribute | Counter attribute |
---|---|---|
appendix |
|
|
example |
|
|
image |
|
|
listing, source |
|
|
table |
|
|
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:
Block content
If you unset the example-caption
attribute, the caption will not be prepended to the 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:
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.