---
title: "Coding guidelines for reST files"
manual: "How to Document"
version: "main"
permalink: "https://docs.typo3.org/permalink/h2document:format-rest-cgl"
source: "Advanced/CodingGuidelines.rst"
modified: "2026-09-14T09:38:54+00:00"
---

# Coding guidelines for reST files

## Basic formatting rules

### Encoding

-   use utf-8

### Whitespace and indentation

> [!IMPORTANT]
> Always use indentation levels correctly. Your code may not
> be rendered as expected if you do not.

-   remove white space from the end of lines (= no trailing tabs or spaces)
-   don't use tabs
-   one indentation level of reST consists of **four spaces**
-   code examples indent with **two spaces**, whatever the language they are
    written in. An example that nests a few levels deep still has to fit the
    line length below, and four spaces per level spends that budget on white
    space. This is the one point where the documentation departs on purpose
    from the indentation a language uses in a real project, PSR-12 included
-   directive and hyperlink target markers use two spaces after `..`,
    e.g. `..  note::` or `..  _label:`
-   list markers are followed by enough spaces to line up item text at a
    4-space column: 3 spaces after a single-character marker (`*`, `-`),
    2 spaces after a two-character enumerator (`#.`, `1.`), 1 space
    after longer enumerators (`10.`)

Example:

```rst
..  image:: /_Images/a4.jpg
    :alt: Left floating image
    :target: https://typo3.org
    :class: with-shadow
```

-   lines 2-4 must be indented one level (4 spaces)

### Line length

-   Keep lines shorter than 80 characters.
-   if in doubt about the length: use short lines!

    -   That way reST is readable as source as well
    -   Files can be easily edited directly on GitHub
    -   Files can be compared in a diff view

### `.editorconfig`

Most of our documentation projects contain an .editorconfig file.

Use this file to setup your editor / IDE correctly. With some, everything will
just work automatically. With others, you will need to download a plugin. This
is explained on the [Editorconfig](http://EditorConfig.org) page.

The file below is the master copy. Every documentation repository uses it
unchanged, so that a change of style is made in one place and copied out:

**.editorconfig**

```ini
# EditorConfig is awesome: https://EditorConfig.org

# Master copy, used unchanged by every TYPO3 documentation repository:
# https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument

root = true

# Code examples indent two spaces, whatever the language, so that a nested
# example still fits the line length the prose around it is wrapped to
[*]
charset = utf-8
end_of_line = lf
indent_style = space
indent_size = 2
insert_final_newline = true
trim_trailing_whitespace = true

# reStructuredText is the exception: one indentation level is four spaces
[{*.rst,*.rst.txt}]
indent_size = 4
max_line_length = 80

[*.md]
max_line_length = 80

# Makefiles do not work without real tabs
[{Makefile,_Makefile,**.mk}]
indent_style = tab

# In a patch a leading or trailing space is content, not whitespace
[*.diff]
trim_trailing_whitespace = false
```

It instructs your editor / IDE to:

-   use utf8 as encoding (line 11)
-   use spaces instead of tabs (line 13)
-   indent code examples with two spaces (line 14) and reST with four
    (line 20)
-   remove trailing whitespace (line 16)
-   keep the tabs in a `Makefile`, which does not work without them
    (line 28)

### Special characters

The only way to include "special" characters is to use them directly

## Headline underlining

In reStructuredText it is possible to use any type of underlining. The first
used will be recognized as level 1 etc.

However, adhering to the standard for TYPO3 documentation makes it easier for
other contributors to find their way around a file and pick the correct underlining
for the header level.

Use the conventions as defined in [Headlines and anchors](https://docs.typo3.org/permalink/h2document:headlines-and-sections).

This underlining is used **per (.rst) file**. It does not matter where in the toctree
the file is. You always start with underlining for level 1 (title) in each
file:

```rst
========
1. Title
========

2. Header Level 1
=================

3. Header Level 2
-----------------

4. Header Level 3
~~~~~~~~~~~~~~~~~

5. Header Level 4
"""""""""""""""""

6. Header Level 5
'''''''''''''''''

7. Header Level 6
^^^^^^^^^^^^^^^^^

8. Header Level 7
#################

etc.
```

## How to add version hints

Example, how you can point out **deprecations**:

```rst
.. deprecated:: 10.2
   The hook shown here is deprecated since TYPO3 10.2 - use a custom
   :ref:`PSR-15 middleware<request-handling>` instead.
```

New **feature**:

```rst
.. versionadded:: 10.2
   Starting with TYPO3 10.2 hooks and signals have been replaced by a PSR-14 based
   event dispatching system.
```

Changes:

```rst
.. versionchanged:: 2.3.1
   This feature was changed ...
```

For more information, see the open issue:

-   [Should we display version hints](https://github.com/TYPO3-Documentation/T3DocTeam/issues/14)

## Link to Changelog

Linking to the [changelog](https://docs.typo3.org/c/typo3/cms-core/main/en-us/Index.html) should not be necessary, if all
relevant information has been transferred to the documentation, but it is not
discouraged either.

The changelog has a title anchor, so you can easily link to it with `:ref:`.

```rst
:ref:`ext_core:feature-101544-1691063522`
```

which outputs the link:

[Feature: #101544 - Introduce PHP attribute to autoconfigure event listeners](https://docs.typo3.org/c/typo3/cms-core/main/en-us/Changelog/13.0/Feature-101544-IntroducePHPAttributeToAutoconfigureEventListeners.html#feature-101544-1691063522)

For this to work, `ext_core` must be defined in `Settings.cfg`:

```ini
ext_core = https://docs.typo3.org/c/typo3/cms-core/main/en-us/
```

## Referring to GUI elements

Use [text role guilabel](https://docs.typo3.org/permalink/h2document:text-roles) for any label that is visible in
the GUI: a backend module, a tab, a button, a field, or a menu entry. If you
describe several of these being selected or clicked one after the other, use
`>` as separator inside a single `:guilabel:`.

> [!IMPORTANT]
> Use the spelling of the word as used in the GUI!

Examples:

```rst
Select :guilabel:`File > Open`
```

-   **How it looks:**

    Select **File > Open**

```rst
Click on :guilabel:`ADMIN TOOLS > Extensions` in the backend.
```

-   **How it looks:**

    Click on **ADMIN TOOLS > Extensions** in the backend.

```rst
Manage extensions in the :guilabel:`Extension Manager` module.
```

-   **How it looks:**

    Manage extensions in the **Extension Manager** module.

## Refering to keystrokes

When pointing out keyboard shortcuts or keystroke sequences, use
[text role](https://docs.typo3.org/permalink/h2document:text-roles) kbd.

Example:

```rst
Press :kbd:`ctrl` + :kbd:`s`
```

-   **How it looks:**

    Press `ctrl` \+ `s`