Section Levels and Titles

Section level syntax

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.

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.

Hide special section titles

The titles of special sections, such as the dedication, can be turned off by assigning untitled to the section’s options attribute (% or options=untitled). This feature is only available for the DocBook backend.

[dedication%untitled]
== Dedication

For S.S.T.--

thank you for the plague of archetypes.