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 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.
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).
= 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:
A document can only have multiple level 0 sections if the
doctypeis set to
The first level 0 section is the document title; subsequent level 0 sections represent parts.
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 (