Autogenerated Section IDs
Unless you specify a custom ID for a section, Asciidoctor automatically generates an ID from the section’s title and assigns it to the section.
Asciidoctor builds an ID from a section title using the following order of events and rules:
Inline formatting is applied (in title substitution order).
All characters are converted to lowercase.
The value of the idprefix attribute (
_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.
Spaces, hyphens, and periods are replaced with the value of the idseparator attribute (
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 toggle ID autogeneration on and off using
sectids and customize the ID prefix and word separator.
To disable the autogeneration of section IDs, unset the
If you disable autogenerated section IDs, and you don’t assign a custom ID to a section, you won’t be able to create cross references to that section. Custom section IDs are still used even when autogenerated section IDs are disabled.