Autogenerate Section IDs

Sections and discrete headings support automatic ID generation. Unless you’ve assigned a custom ID to one of these blocks, or you’ve unset the sectids document attribute, the AsciiDoc processor will automatically generate and assign an ID for the block using the title. This page explains how the ID is derived and how to control this behavior.

How a section ID is computed

The AsciiDoc processor builds an ID from the 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.

Given the following section title:

== Wiley & Sons, Inc.

The processor will produce the following ID:

_wiley_sons_inc

You can toggle ID autogeneration on and off using sectids and customize the ID prefix and word separator.

If the title contains a forward looking xref (i.e., an xref to an element that comes later in document order), you must either assign a custom ID to the block or disable ID generation around the title. Otherwise, the AsciiDoc processor may warn that the reference is invalid. This happens because, in order to generate an ID, the processor must convert the title. This conversion happens before the processor has visited the target element. As a result, the processor is not able to lookup the reference and therefore must consider it invalid.

Disable automatic section ID generation

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

:!sectids:

Custom IDs are still used even when automatic section IDs are disabled.

You can unset this attribute anywhere that attribute entries are permitted in the document. By doing so, you can disable ID generation for only certain sections and discrete headings.

== ID generation on

:!sectids:
== ID generation off
:sectids:

== ID generation on again

If you disable autogenerated section IDs, and you don’t assign a custom ID to a section or discrete headings, you won’t be able to create cross references to that element.