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 for referencing from the URL using inline anchors. This feature works regardless of whether you assign an explicit (primary) ID.

Here’s how to register additional anchors 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]]

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, as shown in the next example.

Example 3. Register additional leading anchor points on a section title with a custom ID
[#primary-id]
== [[secondary-id]][[tertiary-id]]Section Title
These additional IDs are not registered with the referencing system. That means they cannot be used for referencing the section title within the document. They are only intended for assigning additional fragment identifiers to the section title so it can be referenced the from the URL using a URL fragment (aka deep linking). Only the primary ID can be used for referencing the section title within the document.