Section Levels and Titles
A section title represents the heading for a section. Section title levels are specified by two to six equal signs. The number of equal signs in front of the title represents the nesting level (using a 0-based index) of the section.
= 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 (
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
The titles of special sections, such as the dedication, can be turned off by assigning
untitled to the section’s options attribute (
This feature is only available for the DocBook backend.
[dedication%untitled] == Dedication For S.S.T.-- thank you for the plague of archetypes.