Assign Custom IDs and Reference Text

You can assign a custom ID and optional reference text (i.e., label) to a section (see anchor). The custom ID is used in place of the autogenerated ID. This can be useful when you want to define a stable anchor for linking to a section using a cross reference. The reference text is used when referencing the ID without specifying explicit text. This is a good way to centrally manage the automatic reference text that is used to refer to a section.

Here’s an example of a section with a custom ID:

[#tigers-subspecies]
=== Subspecies of Tiger

Here’s an example of a section with a custom ID and reference text:

[[tigers-subspecies,Subspecies]]
=== Subspecies of Tiger

The ID can be written using the following shorthand (though there’s no shorthand yet for the reference text):

[#tigers-subspecies,reftext=Subspecies]
=== Subspecies of Tiger
The value of the reftext attribute must be quoted if it contains spaces or commas.
Asciidoctor recognizes all valid UTF-8 characters in section IDs. When using the double square bracket form, the ID must conform to the XML Name rules, which means the ID must start with a letter, an underscore, or a colon. If you’re generating a PDF from AsciiDoc using a2x and dblatex, see Using UTF-8 titles with a2x to learn about the required latex.encoding=utf8 switch to activate this portability.

Assign additional IDs

A section title can only have a single primary ID. However, it’s possible to register additional IDs on a section title using inline anchors. This feature works regardless of whether you assign a custom ID.

Here’s how to register additional anchor points when using an autogenerated ID:

Example 1. Register additional leading anchor points
== [[secondary-id]][[tertiary-id]]Section Title
Example 2. Register additional trailing anchor points
== Section Title[[secondary-id]][[tertiary-id]]

You can place the anchors anywhere within the section title line. Where you place them is where the anchor will end up in the output, so it’s best to put them either at the beginning or the end. The beginning is the preferred location.

These additional anchor points don’t interfere with the declaration of the primary ID.

Example 3. Register additional leading anchor points on a section title with a custom ID
[#primary-id]
== [[secondary-id]][[tertiary-id]]Section Title