Section IDs, Anchors and Links
If you don’t specify a custom ID for a section, Asciidoctor automatically generates an ID from the section’s title and assigns it to the section.
The ID is derived from the section title as follows:
Inline formatting is applied (in title substitution order).
All characters are converted to lowercase.
The value of the
_by default) is prepended.
Character references, HTML/XML tags, and invalid ID characters are removed.
Refer to the NT-Name section of the XML specification for a list of valid ID characters.
Prior to 1.5.7, HTML/XML tags were not removed and character references and invalid ID characters were replaced with the value of the
Spaces, hyphens, and periods are replaced with the value of the
Repeating separator characters are condensed.
If necessary, a sequence number is appended until the ID is unique within the document.
For example, the section title
Wiley & Sons, Inc. produces the ID
You can customize the replacement characters or toggle ID autogeneration using document attributes.
You can change the ID prefix by setting the
The value of the
idprefix attribute must begin with a valid ID start character and can have any number of additional valid ID characters.
If you want to remove the prefix, set the attribute to an empty value.
If you set the
You can change the word separator using the
Unless empty, the value of the
idseparator must be exactly one valid ID character.
If you don’t want to use a separator, set the attribute to an empty value.
When a document is rendered on GitHub, the
To disable the autogeneration of section IDs, unset the
Custom IDs, covered next, are used even when section IDs are disabled.
|If you disable autogenerated section IDs, and you don’t assign a custom ID to a section, you won’t be able to create xrefs that link to that section.|
You can assign a custom ID and 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. It also centralizes the reference text used to refer to that section.
Here’s an example of a section with a custom ID and reference text:
[[tigers-section,Tigers]] === Subspecies of Tiger
The ID can be written using the following shorthand (though there’s no shorthand yet for the reference text):
[#tigers-section,reftext=Tigers] === Subspecies of Tiger
Asciidoctor permits all valid UTF-8 characters 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
To turn section titles into links, enable the
The default Asciidoctor stylesheet displays linked section titles with the same color and styles as unlinked section titles.