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
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:
== [[secondary-id]][[tertiary-id]]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.
[#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.|