When the document is converted to HTML 5 (using the built-in html5 backend), each section title becomes a heading element where the heading level matches the number of equal signs. For example, a level 1 section (==) maps to an <h2> element.

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

The ID is derived from the section title as follows:

For example, the section title Wiley & Sons, Inc. produces the ID _wiley_sons_inc. You can customize the replacement characters or toggle ID auto-generation using document attributes.

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.

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

You can change the word separator using the idseparator attribute. Unless empty, the value of the idseparator must be exactly one valid ID character.

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

To disable the auto-generation of section IDs, unset the sectids attribute.

Custom IDs, covered next, are used even if auto-generation of section IDs is disabled.

You can assign a custom ID and optional reference text (i.e., label) to a section (see Defining an Anchor). The custom ID is used in place of the auto-generated ID. This can be useful when you want to define a stable anchor for linking to a section using a cross reference. The reference text is used when referencing the ID without specifying explicit text. This is a good way to centrally manage the automatic reference text that is used to refer to a section.

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

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

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

The value of the reftext attribute must be quoted if it contains spaces or commas.

While a section title can only have a single primary ID, as of Asciidoctor 1.5.7, it’s possible to register additional anchor points on a section title using inline anchors. This feature works regardless of whether you assign a custom ID.

Here’s how to register additional anchor points when using an auto-generated ID:

You can place the anchors anywhere you want within the section title line. Where you place them is where the anchor will end up in the output, so it’s best to put them either at the beginning or the end. The beginning is the preferred location.

These additional anchor points don’t interfere with defining a custom ID.

Alternately, you can move the primary ID inline by placing it after the section title, offset by a single space.

However, we don’t recommend defining the primary ID inline as it’s more difficult to read.

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.

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.

Asciidoctor allows section numbering to be toggled on and off throughout a document. You can enable section numbers using the sectnums attribute.

You can also use this attribute entry above any section title in the document to toggle the auto-numbering setting. When you want to turn off the numbering, add an exclamation point to the end of the attribute name:

For regions of the document where section numbering is turned off, the section numbering will not be incremented.

Given:

The sections will be numbered as follows:

Asciidoctor will always curtail incrementing the section number in regions of the document where section numbers are off.

If sectnums is set on the command line (or API), that overrides the value set in the document header, but it does not prevent the document from toggling the value for regions of the document.

If sectnums! is set on the command line (or API), then the numbers are disabled regardless of the setting within the document.

To make a discrete heading, you add the discrete attribute to any section title. A discrete heading is styled in a manner similar to a section title, but is not part of the section hierarchy (i.e., and thus excluded from section nesting requirements), it does not enclose subsequent blocks, and it is not included in the table of contents. The discrete style effectively demotes the section title to a normal heading.

Here’s an example of a discrete heading in use.

Asciidoctor provides styles for the frontmatter and backmatter sections commonly found in journal articles, academic papers, and books. The styles are:

These styles are available to the article and book document types, with the exception of the part introduction style which is exclusive to books.

In general, the section style attribute is set above a level 1 section title or block of text. For instance, the example below shows how to label a section as an abstract.

The structure and usage rules for each section style is explained in Structuring, Navigating, and Referencing Your Content.