Headlines and Sections

reStructuredText (reST) does not exactly have the notion of “headlines”. Text is split into “sections” instead. Those sections are identified by titles which - in the end - appear as headlines as we know them.

TYPO3 uses these conventions.

  1. Use underlining plus overlining with === for the first section title of a file. The first section title is the “document title” (doctitle) of that file and will appear in the menu. Every .rst file should have a doctitle:

    ========
    DocTitle
    ========
    
  2. Then use underlining only:

    1.  ==========  for the first  level
    2.  ----------  for the second level
    3.  ~~~~~~~~~~  for the third  level
    4.  """"""""""  for the fourth level
    
  3. More levels will be rarely used. For sake of completeness here is the whole hierarchy the automatic conversion tools uses. Stick to this order if more levels are needed:

    5.  ''''''''''
    6.  ^^^^^^^^^^
    7.  ##########
    8.  **********
    9.  $$$$$$$$$$
    10. ``````````
    plus:  +;.,_/%&!  in that order
    

Example

========
DocTitle
========

About this document ...

Topic 1
=======
Here we go.

Subtopic 1.1
------------
Here we dive deeper

Subsubtopic 1.1.1
~~~~~~~~~~~~~~~~~
And this is even more specific.

Topic 2
=======
...

Syntax

Length of Underlines

The length of the underlines must at least have the length of the text. It may be longer, not shorter.

Example 1: This Works

=========
Example 1
=========

Example 2: This Works Too

==============
Example 1
==============

Example 3: This Does not Work

=======
Example 1
=======

Additional Information

  • Docutils: Read about sections in the Docutils documentation for the most fundamental description.
  • Sphinx is explaining sections as well.