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.

How a section ID is assembled

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 (_ 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.