你可以给一个块分配一个标题，无论它是使用其样式名称还是分隔符设置样式的。

标题语法

块标题定义在块属性列表、开放定界符或块内容之上的独立行上——无论哪个先出现。如标题语法所示，该行必须以点（.）开头，紧接着是标题文本。块标题必须只占用单行，因此不能换行。

标题语法
.This is the title of a sidebar block
****
This is the content of the sidebar block.
****

接下来的章节将展示如何为带有定界符的块和带有属性列表的块添加标题。

给定界定块添加标题

任何有界限的块都可以有一个标题。如果块没有属性列表，在开头定界符的正上方新行输入标题。在给定界定块添加标题中的定界字面块标题为_终端输出_。

给定界定块添加标题
.Terminal Output (1)
.... (2)
From github.com:asciidoctor/asciidoctor
 * branch        main   -> FETCH_HEAD
Already up to date.
....

  1. 区块标题需在新的一行输入。标题必须以点（.）开始。标题的点和第一个字符之间不要加空格。

  2. 如果你不给一个块应用属性，就在标题后面直接新起一行输入开头分隔符。

给定界定块添加标题的结果如下所示。

终端输出
From github.com:asciidoctor/asciidoctor
 * branch        main   -> FETCH_HEAD
Already up to date.

在下一部分中，您将看到如何在具有属性列表的块上放置标题。

给带属性的块添加标题

当你给块应用属性时，标题被放置在属性列表（或列表）上方的行。 给限定的源代码块添加标题 显示了一个带有标题 指定 GitLab CI 阶段 的分隔源代码块。

给限定的源代码块添加标题
.Specify GitLab CI stages (1)
[source,yaml] (2)
----
image: node:16-buster
stages: [ init, verify, deploy ]
----

  1. 区块的标题是在新的一行输入的。

  2. 区块的属性列表在标题后直接新起一行输入。

显示下面的给限定的源代码块添加标题结果。

指定 GitLab CI 阶段
image: node:16-buster
stages: [ init, verify, deploy ]

如给一个没有界定符的块添加标题所示，当一个区块没有界定时，区块的标题位于属性列表的上方。

给一个没有界定符的块添加标题
薄荷
[侧边栏]
薄荷有着全球征服的幻想。
如果你不将它种植在容器中，它将占领你的花园。

“给一个没有界定符的块添加标题的结果如下所示。”

薄荷
薄荷有征服全球的愿景。如果你不将它种植在容器中，它将接管你的花园。

您可能会注意到，与前面渲染的列表和源代码块示例中的标题不同，侧边栏的标题是居中的，并显示在侧边栏的背景内。块的标题显示方式取决于您应用于 AsciiDoc 文档的转换器和样式表。

带字幕的标题

几个块上下文支持带标题的标注。一个[.term]*带标题的标注*是一个标题，它以一个标签和一个数字为前缀，后跟一个点（例如，表 1. 属性）。

标题仅在相应的标题属性被设置时使用。否则，将显示原始标题。

以下表格列出了支持带标题的块元素及转换器用于生成和控制它们的属性。

Table 1. 支持标题字幕的区块
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

除了用于列表和源代码块（listing-caption）的属性外，所有标题属性都是默认设置的。编号是连续的，自动计算的，并且存储在相应的计数器属性中。

让我们假设你已经如下向一个示例块添加了一个标题：

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

区块标题将以标题标签和序号显示，如下所示：

Example 1. 支持标题字幕的区块

块内容

如果你取消设置`example-caption`属性，标题前将不会添加标题文本。

支持标题字幕的区块

块内容

计数器属性（例如，example-number）可以用来影响具有该上下文的第一个块的起始编号，或者用于随后出现时序列中选择的下一个编号。然而，这种做法应该谨慎使用。

标题可以通过在块上使用`caption`属性来重写。`caption`属性的值将替换整个标题，包括标题前面的空间。

定义自定义块标题的方法如下：

.Block Title
[caption="示例 {counter:my-example-number:A}: "]
====
块内容
====

块显示将会如何呈现自定义标题：

示例 A:区块标题

块内容

请注意，我们在caption属性的值中使用了一个counter属性来创建一个自定义编号序列。

如果您使用xref引用带有自定义标题的区块，可能无法获得预期的结果。因此，在定义自定义标题时，最好总是定义自定义的xreftext。