Section Titles and Levels

Sections partition the document into a content hierarchy. A section is an implicit enclosure. Each section begins with a title and ends at the next sibling section, ancestor section, or end of document. Nested section levels must be sequential. A section can be a child of a document or another section, but it cannot be the child of any other block (i.e., you cannot put a section inside of a delimited block or list).

Section level syntax

A section title marks the beginning of a section and also acts as the heading for that section. The section title must be prefixed with a section marker, which indicates the section level. The number of equal signs in the marker represents the section level using a 0-based index (e.g., two equal signs represents level 1). A section marker can range from two to six equal signs and must be followed by a space.

The section title line is interpreted as paragraph text if it’s found inside of a non-section block unless it marked as a discrete heading.

In the HTML output, the section title is represented by a heading tag. The number of the heading tag is one more than the section level (e.g., section level 1 becomes an h2 tag). The section level ranges from 0-5. This limit was established primarily due to the fact that HTML only provides heading tags from h1 to h6 (making level 5 the upper limit).

Example 1. Section titles available in an article doctype
= Document Title (Level 0)

== Level 1 Section Title

=== Level 2 Section Title

==== Level 3 Section Title

===== Level 4 Section Title

====== Level 5 Section Title

== Another Level 1 Section Title

The section titles are rendered as:

Document Title (Level 0)

Level 1 Section Title

Level 2 Section Title

Level 3 Section Title

Level 4 Section Title
Level 5 Section Title

Another Level 1 Section Title

Section levels must be nested logically. There are two rules you must follow:

  1. A document can only have multiple level 0 sections if the doctype is set to book.

    • The first level 0 section is the document title; subsequent level 0 sections represent parts.

  2. Section levels cannot be skipped when nesting sections (e.g., you can’t nest a level 5 section directly inside a level 3 section; an intermediary level 4 section is required).

For example, the following syntax is illegal:

= Document Title

= Illegal Level 0 Section (violates rule #1)

== First Section

==== Illegal Nested Section (violates rule #2)

Content above the first section title is designated as the document’s preamble. Once the first section title is reached, content is associated with the section it is nested in.

== First Section

Content of first section

=== Nested Section

Content of nested section

== Second Section

Content of second section
In addition to the equals sign marker used for defining section titles, Asciidoctor recognizes the hash symbol (#) from Markdown. That means the outline of a Markdown document will be converted just fine as an AsciiDoc document.

Titles as HTML headings

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.