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,reftext=Subspecies]
=== Subspecies of Tiger

The value of the reftext attribute must be quoted if it contains spaces or commas.

The ID and reference text can also be defined using the legacy block anchor syntax:

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

When using the block anchor syntax, the ID must conform to the XML Name rules, which means the ID must start with a letter, an underscore, or a colon.

AsciiDoc allows all valid UTF-8 characters to be used in section IDs. 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 auxiliary IDs

A section title can only have a single primary ID. However, it’s possible to register auxiliary 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.

If possible, you should avoid adding inline anchors on a section title. However, if you need to be able to link to that section from a URL using alternate fragment identifiers, this is what you need to use.

Here’s how to register auxiliary IDs using inline anchors when using an autogenerated ID:

Example 1. Register auxiliary IDs at the beginning of the section title

== [[secondary-id]][[tertiary-id]]Section Title

Example 2. Register auxiliary IDs at the end of the section title

== Section Title[[secondary-id]][[tertiary-id]]

Where you place the inline anchor is where the anchor will end up in the output. 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 auxiliary IDs on a section title with an explicit ID

[#primary-id]
== [[secondary-id]][[tertiary-id]]Section Title

These auxiliary 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 auxiliary 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.