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.

How a section ID is assembled

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 (_ by default)

  • 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 _wiley_sons_inc. You can toggle ID autogeneration on and off using sectids and customize the ID prefix and word separator.

Disable section ID generation

To disable the autogeneration of section IDs, unset the sectids attribute.


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.