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 non-word characters (except for space, hyphen, and period) are removed.

  • 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.

The generated ID can be expected to be safe to use in an HTML document. However, it’s important to understand that the generated ID does not necessarily conform to an NT-Name, as required by the XML specification. If you intend to produce DocBook from your AsciiDoc document(s), and your section titles uses word characters that are not permitted in an XML ID, the onus is on you to either provide an explicit ID that is conforming, or encode those invalid ID characters using a character reference (e.g., Ⅱ).

With those rules in mind, 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 section 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.