Note

This version of the guide covers the new PHP-based rendering of Documentation with the TYPO3 Documentation theme.

If the project you are looking at has a file Documentation/guides.xml it is using the new rendering.

Otherwise, consider to migrate the Documentation or head over to the legacy version of this guide: How to document, Sphinx based.

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.

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 title, each title should have a link anchor. In Link anchors we describe our recommended best way how to build a link anchor in the official TYPO3 documentation. Here you see a title and a link anchor in action:

..  _doc-title:

==============
Document Title
==============

Then use underlining only:

1.  ==========  for the first  level
2.  ----------  for the second level
3.  ~~~~~~~~~~  for the third  level
4.  """"""""""  for the fourth level

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

..  _document-title:

==============
Document Title
==============

About this document ...

..  _topic-1:

Topic 1
=======

Here we go.

..  _subtopic-1-1:

Subtopic 1.1
------------

Here we dive deeper


..  _subsubtopic-1-1-1:

Subsubtopic 1.1.1
~~~~~~~~~~~~~~~~~

And this is even more specific.

..  _topic-2:

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

Syntax

Length of Underlines

The length of the underlines should have the same length like the text. It should not be longer or shorter.

Example 1: This Works

..  _example-1:

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

Example 2: These headlines work but do not abide to the coding guidelines

Here we see how we should not do it. The underlines are too long or too short.

..  _example-2:

==============
Example 2
==============

# Underline too long

..  _example-3:

=======
Example 3
=======

# Underline too short