分配自定义ID和参考文本

您可以为一个章节分配一个自定义ID和可选的参考文本（即标签）（参见锚点）。自定义ID将替代自动生成的ID使用。这在您希望为使用交叉引用链接到某个章节定义一个稳定的锚点时很有用。引用文本在未指定显式文本引用ID时使用。这是一个很好的方式来集中管理用于引用章节的自动引用文本。

这是一个带有自定义ID的部分的示例：

Unresolved directive in custom-ids.adoc - include::example$section.adoc[tag=with-anchor-shorthand]

这里是一个带有自定义ID和参考文本的节的例子：

Unresolved directive in custom-ids.adoc - include::example$section.adoc[tag=with-anchor-and-reftext-shorthand]

Important

如果reftext属性的值包含空格或逗号，那么它的值必须加上引号。

ID和参考文本也可以使用传统的块锚点语法来定义。

Unresolved directive in custom-ids.adoc - include::example$section.adoc[tag=with-anchor-and-reftext]

当使用块锚点语法时，ID 必须符合 https://www.w3.org/TR/REC-xml/#NT-Name [XML 名称] 规则，这意味着 ID 必须以字母、下划线或冒号开头。

Important

AsciiDoc 允许在节ID中使用所有有效的 UTF-8 字符。如果你正在使用 a2x 和 dblatex 从 AsciiDoc 生成 PDF，请查看使用 a2x 的 UTF-8 标题了解激活此可移植性所需的 latex.encoding=utf8 开关。

分配辅助ID

一节标题只能有一个主要ID。然而，有可能在一个节标题上注册辅助ID，以便通过内联锚点从URL进行引用。无论是否分配了显式的（主要）ID，这个功能都是有效的。

Caution

如果可能的话，你应该避免在节标题上添加内联锚点。然而，如果你需要能够使用替代的片段标识符从URL链接到那个部分，这就是你需要使用的。

当使用自动生成的ID时，以下是如何通过行内锚点来注册辅助ID的方法：

在章节标题的开头注册辅助ID

== [[secondary-id]][[tertiary-id]]章节标题

在章节标题的末尾注册辅助ID

== 节标题[[secondary-id]][[tertiary-id]]

你在输出中放置内联锚点的位置就是锚点最终所在的位置。开始位置是首选位置。

这些额外的锚点不会干扰主ID的声明，如下一个例子所示。

在具有显式ID的节标题上注册辅助ID

[#primary-id]
== [[secondary-id]][[tertiary-id]]章节标题

Important

这些辅助ID没有在参考系统中注册。这意味着它们不能用于文档内部引用章节标题。它们仅用于为章节标题分配辅助的片段标识符，以便可以使用URL片段（又称深度链接）从URL中引用。只有主ID可以用于文档内部引用章节标题。