Chapter 11. Titles

Document and section titles can be in either of two formats:

11.1. Two line titles

A two line title consists of a title line, starting hard against the left margin, and an underline. Section underlines consist a repeated character pairs spanning the width of the preceding title (give or take up to two characters):

The default title underlines for each of the document levels are:

Level 0 (top level):     ======================
Level 1:                 ----------------------
Level 2:                 ~~~~~~~~~~~~~~~~~~~~~~
Level 3:                 ^^^^^^^^^^^^^^^^^^^^^^
Level 4 (bottom level):  ++++++++++++++++++++++

Examples:

Level One Section Title
-----------------------
Level 2 Subsection Title
~~~~~~~~~~~~~~~~~~~~~~~~

11.2. One line titles

One line titles consist of a single line delimited on either side by one or more equals characters (the number of equals characters corresponds to the section level minus one). Here are some examples:

= Document Title (level 0) =
== Section title (level 1) ==
=== Section title (level 2) ===
==== Section title (level 3) ====
===== Section title (level 4) =====
[Note]
  • One or more spaces must fall between the title and the delimiters.
  • The trailing title delimiter is optional.
  • The one-line title syntax can be changed by editing the configuration file [titles] section sect0sect4 entries.

11.3. Floating titles

Setting the title’s first positional attribute or style attribute to float generates a free-floating title. A free-floating title is rendered just like a normal section title but is not formally associated with a text body and is not part of the regular section hierarchy so the normal ordering rules do not apply. Floating titles can also be used in contexts where section titles are illegal: for example sidebar and admonition blocks. Example:

[float]
The second day
~~~~~~~~~~~~~~

Floating titles do not appear in a document’s table of contents.