Change the ID Prefix and Separator
When an AsciiDoc processor auto-generates section IDs, it begins the value with an underscore and uses a hyphen between each word.
These characters can be customized with the idprefix and idseparator attributes.
Change the ID prefix
By default, the AsciiDoc processor begins an auto-generated section ID with an underscore (_).
This default can cause problems when referencing the ID in an xref (either within the same file or a deep link to another file).
The leading underscore may get paired with an underscore somewhere else in the paragraph, thus resulting in unexpected text formatting.
One workaround is to disrupt the match by prefixing the ID with {empty} (e.g., {empty}_section_title) or using an attribute to refer to the target.
Instead, we strongly encourage you to customize the ID prefix.
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.
|