Section IDs, Anchors and Links

Autogenerated IDs

If you don’t specify a custom ID for a section, Asciidoctor automatically generates an ID from the section’s title and assigns it to the section.

The ID is derived from the section title as follows:

  • 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, and invalid ID characters are removed.

    • Refer to the NT-Name section of the XML specification for a list of valid ID characters.

    • Prior to 1.5.7, HTML/XML tags were not removed and character references and invalid ID characters were replaced with the value of the idseparator attribute (_ by default).

  • 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 customize the replacement characters or toggle ID autogeneration using document attributes.

Change the ID prefix

You can change the ID prefix by setting the idprefix attribute. The value of the idprefix attribute 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 blank, 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

You can change the word separator using 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.

Disable ID generation

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

:sectids!:

Custom IDs, covered next, are used even when section IDs are disabled.

If you disable autogenerated section IDs, and you don’t assign a custom ID to a section, you won’t be able to create xrefs that link to that section.

Assign custom IDs

You can assign a custom ID and reference text (i.e., label) to a section (see anchor). The custom ID is used in place of the autogenerated ID. This can be useful when you want to define a stable anchor for linking to a section using a cross reference. It also centralizes the reference text used to refer to that section.

Here’s an example of a section with a custom ID and reference text:

[[tigers-section,Tigers]]
=== Subspecies of Tiger

The ID can be written using the following shorthand (though there’s no shorthand yet for the reference text):

[#tigers-section,reftext=Tigers]
=== Subspecies of Tiger
Asciidoctor permits all valid UTF-8 characters in section IDs. If you’re generating a PDF from AsciiDoc using a2x and dblatex, see Using UTF-8 titles with a2x to learn about the required latex.encoding=utf8 switch.

To turn section titles into links, enable the sectlinks attribute. The default Asciidoctor stylesheet displays linked section titles with the same color and styles as unlinked section titles.

Add § to section titles

When the sectanchors attribute is enabled on a document, an anchor (empty link) is added before the section title. The default Asciidoctor stylesheet renders the anchor as a section entity (§) that floats to the left of the section title.