Change the ID Prefix and Separator

When Asciidoctor runs, it prefixes autogenerated section IDs with an underscore and separates each word with an underscore. These characters can be customized with the idprefix and idseparator attributes.

Change the ID prefix

By default, Asciidoctor prefixes autogenerated section IDs with an underscore (_). You can change this prefix by setting the idprefix attribute and assigning it a new value. The value of idprefix must begin with a valid ID start character and can have any number of additional valid ID characters.

:idprefix: id_

If you want to remove the prefix, set the attribute to an empty value.

:idprefix:

If you set the idprefix to empty, you could end up generating IDs that are invalid in DocBook output (e.g., an ID that begins with a number) or that match a built-in ID in the HTML output (e.g., header). In this case, we recommend either using a non-empty value of idprefix or assigning explicit IDs to your sections.

Change the ID word separator

The default section ID word separator is an underscore (_). You can change the separator with the idseparator attribute. Unless empty, the value of the idseparator must be exactly one valid ID character.

:idseparator: -

If you don’t want to use a separator, set the attribute to an empty value.

:idseparator:

When a document is rendered on GitHub, the idprefix is set to an empty value and the idseparator is set to -. These settings are used to ensure that the IDs generated by GitHub match the IDs generated by Asciidoctor.