Autogenerated Section IDs
Unless you specify a custom ID for a section or discrete heading, the AsciiDoc processor will automatically generate an ID from the block’s title and assign it to the block. This automatic ID generation is applied to both section titles and discrete headings.
The AsciiDoc processor 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 (not their contents), 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.