---
title: "Coding guidelines for reStructured text files"
manual: "How to Document"
version: "main"
permalink: "https://docs.typo3.org/permalink/h2document:cgl"
source: "Reference/CodingGuidelines/Index.rst"
rendered: "2026-09-26T10:48:44+00:00"
---

# Coding guidelines for reStructured text files {#cgl}

In the official documentation files we try to follow the following coding
guidelines:

-   Indentation of 4 spaces, this includes
    [lists](https://docs.typo3.org/permalink/h2document:rest-lists), directives,
    [Code blocks](https://docs.typo3.org/permalink/h2document:writing-rest-codeblocks-with-syntax-highlighting),
    and other blocks that need to be indented in ReST.
-   Wrap lines at 80 chars where possible
-   We avoid abbreviations and colloquial language. When we use abbreviations
    they should be introduced in the same section.
-   Each ReST file must have a main header.
-   Each ReST file must include `..  include:: /Includes.rst.txt` to display
    global messages, for example for outdated versions.
-   It is highly recommended to use `:navigation-title: My Title` at the top
    of each file to provide a shorter title to be displayed in the menu.
    See [Navigation title: A page title displayed in menus](https://docs.typo3.org/permalink/h2document:navigation-title).

**Documentation/Introduction.rst**

```plaintext
:navigation-title: Introduction

..  include:: /Includes.rst.txt
..  _introduction:

=====================
Introduction to MyExt
=====================

This extension provides a simple way to display weather data.

*   It fetches data from an external API and processes it in a way that allows
    it to be cached and reused efficiently throughout the TYPO3 site.
*   The results are cached for performance.
*   You can configure the output in the backend.

This extension is compatible with TYPO3 v12 and above.

```

## Rules for code examples {#cgl-code}

-   Wrap code examples at 80 chars where possible to avoid horizontal scrolling.
-   Code examples longer then a few lines should go in external files to be
    included.
-   All code examples should lint. They should demonstrate best practices.
    Where best practices would over complicate things, mention that this is not
    a best practice but used for demonstration.

**Documentation/Installation.rst**

```plaintext
:navigation-title: Installation

..  include:: /Includes.rst.txt
..  _installation:

========================================
Installation and usage of this extension
========================================

You can install the extension like this:

..  code-block:: bash

    composer install myvendor/my-extension

..  _config:

Create a configuration file
===========================

If you want to see a more complete configuration, refer to the example below:

..  literalinclude:: _codesnippets/_config.yaml
    :caption: EXT:my_ext/Configuration/MyConfig/config.yaml

```

## Rules headlines {#cgl-headlines}

-   Headlines are in sentence case.
-   Each headline should be possible to understand without context. This improves
    search results in the internal search and search engines.
-   Use the official order for marking headlines. The page title is overlined
    and underlined with `=`, headlines of level 2 are underlined with `=`,
    level 3 with `-` and level 4 with `~`.
-   Each headline should have a unique anchor so that permalinks to the headline
    can be generated.

**Documentation/MyDocs.rst**

```plaintext
..  _rest-cheat-sheet:

=============================
Cheat sheet: reStructuredText
=============================

Some text.

..  _h2-headline:

H2 Headline
===========

Lorem Ipsum

..  _h3-headline:

H3 Headline
-----------

Some more text

```

See [Headlines and Anchors](https://docs.typo3.org/permalink/h2document:headlines-and-sections)
for more headline levels.