---
title: "Add Documentation"
manual: "TYPO3 Core Contribution Guide"
version: "main"
permalink: "https://docs.typo3.org/permalink/t3contribute:adding-documentation"
source: "AddingDocumentation/Index.rst"
rendered: "2026-09-26T04:50:59+00:00"
---

# Add Documentation {#adding-documentation}

**Quick links:**

-   [the reST cheat sheet](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Basics/RstCheatSheet.html#Formatting-with-reST)
-   [Coding guidelines for reST files](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Advanced/CodingGuidelines.html#format-rest-cgl)
-   [the reST cheat sheet](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Basics/RstCheatSheet.html#rest-cheat-sheet)
-   [Rendering the Documentation folder locally with Docker](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Howto/RenderingDocs/Index.html#render-documentation-with-docker)

The documentation [TYPO3 Core Changelog](https://docs.typo3.org/c/typo3/cms-core/main/en-us/Index.html#typo3-core-changelog)
and documentation for
[System Extensions](https://docs.typo3.org/Index.html#System-Extensions)
is maintained in the Core.

## Quickstart to contribute documentation {#adding-documentation-quickstart}

To work on the Core documentation of TYPO3, you need to work with the main TYPO3
mono-repository. You can **not** contribute Documentation patches on single read-only
repositories like [https://github.com/typo3-cms/felogin](https://github.com/typo3-cms/felogin) through the GitHub interface!

You can, however, use the GitHub interface and contribute
to [https://github.com/TYPO3/typo3/tree/main/typo3/sysext/felogin](https://github.com/TYPO3/typo3/tree/main/typo3/sysext/felogin).
Submitting a GitHub PR will result in a GitHub Action workflow that closes your
PR, transfers it to forge, transfers it to gerrit, and link them to each other. That workflow
can be prone to errors though, especially if a branch other than `main` is involved.

So, if possible you could better follow the [Quickstart](https://docs.typo3.org/permalink/t3contribute:quickstart) guide to
set up a Core contribution installation. A lot can be left out,
as you do not necessarily even need a TYPO3 instance running when you only want to contribute
documentation.

The minimal steps to contribute documentation "the right way" (and to allow you to properly
participate in our review workflow) is this:

1.  Prerequisites

    From the [Quickstart Prerequisites](https://docs.typo3.org/permalink/t3contribute:quickstart-prerequisites) you need:

    1.  Operating System
    1.  GIT client
    1.  SSH client + keys
    1.  Optional Bonus: Docker (to render documentation), a suitable Text-Editor
1.  Set-up accounts

    You need all of the [Quickstart Accounts](https://docs.typo3.org/permalink/t3contribute:quickstart-accounts) (My TYPO3, GitHub, Gerrit, Forge)
1.  Set-up GIT

    Set up and clone the TYPO3 mono-repository as described in [Quickstart GIT](https://docs.typo3.org/permalink/t3contribute:quickstart-git).

    Note: the steps [Set up DDEV](https://docs.typo3.org/permalink/t3contribute:quickstart-ddev) and
    [Set up TYPO3](https://docs.typo3.org/permalink/t3contribute:quickstart-typo3) are not needed for Documentation-only
    use.
1.  Start documenting

    Now you can start editing files in, for example, `typo3/sysext/felogin/Documentation/Index.rst` and
    when you are done, you can render the documentation (see
    [Render any system documentation locally](https://docs.typo3.org/permalink/t3contribute:render-extension)) to verify
    the look of your changes.
1.  Create issue

    Once you feel comfortable and happy with your patch, you go to [create an issue on Forge](https://forge.typo3.org/projects/typo3cms-core/issues/new). Choose the category `Documentation`
    and enter an appropriate description like:

    > **Tracker**: Task
    >
    > **Subject**: Add example for EXT:felogin RedirectLoginHandler
    >
    > **Description**: (Describe what kind of documentation changes you made. Mention to which TYPO3 version it applies)
1.  Submit patch

    Now follow the steps outlined in
    [Quick Start: Create a patch](https://docs.typo3.org/permalink/t3contribute:quickstart-patch), and refer to the
    Documentation files
    you edited, instead of the PHP files given as examples there. This will then submit your patch
    to our Gerrit review instance.

## Changelog {#changelog}

Some patches require a `.rst` (reStructuredText) Changelog file describing the change.
Not all patches
need an entry in the Changelog. Check the list below. Also see the current
[TYPO3 Core Changelog](https://docs.typo3.org/c/typo3/cms-core/main/en-us/Index.html#typo3-core-changelog)
for some examples.

Every file may optionally contain tags, but it must contain at least a
`NotScanned`, `PartiallyScanned` or `FullyScanned` tag for the extension scanner.
See [Extension scanner](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/HowTo/UpdateExtensions/ExtensionScanner.html#extension-scanner) in TYPO3 Explained for more
information.

### Render the Changelog locally {#render-the-changelog}

If you have [Docker](https://www.docker.com) or [Podman](https://podman.io/)
installed you can try out the rendering of the changelog locally:

**Docker**

```bash
cd typo3/sysext/core
docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --config=Documentation
xdg-open "Documentation-GENERATED-temp/Index.html"
```

**Podman**

```bash
cd typo3/sysext/core
docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --config=Documentation
xdg-open "Documentation-GENERATED-temp/Index.html"
```

### Render any system documentation locally {#render-extension}

As above, you can render any extension locally, too. You need to change the directory to the extension
directory you want to render. For `EXT:felogin` that would be:

**Docker**

```bash
cd typo3/sysext/felogin
docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --config=Documentation
xdg-open "Documentation-GENERATED-temp/Index.html"
```

**Podman**

```bash
cd typo3/sysext/felogin
docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --config=Documentation
xdg-open "Documentation-GENERATED-temp/Index.html"
```

### Forger reST Helper {#rest-file-generator}

Use the [Forger reST Helper](https://forger.typo3.com/utilities/rst) to
generate changelogs.

This is strongly recommended because the tool will generate correctly
formatted files. You can always add more to the .rst file directly later.

Select the type of rst snippet you want to create, enter your issue number
and click the search button. Select appropriate tags.

When you are done, copy the generated text and create a file with the same
name as suggested in the generator in
`typo3/sysext/core/Documentation/Changelog/...`.

### Types of Changes {#types-of-changes}

There are four different types of changes
which have to follow a certain format and **always**
need to go into `typo3/sysext/core/Documentation/Changelog/<release>/`.

Choose one which fits your patch:

#### Breaking Changes {#documenting-changelog-breaking-changes}

A patch moved or removed a specific part of core functionality
that may break extensions if they use this part.

**Mandatory sections:**

1.  **Description** \- why things had to break backwards compatibility.
1.  **Impact** \- how will the change affect your installation.
1.  **Affected Installations** \- describe scenarios under which circumstances
    a TYPO3 install will be affected by this change.
1.  **Migration** \- provide instructions what needs to be done to get things
    working again. Explicitly mention if no migration is possible.

#### Deprecations {#documenting-changelog-deprecations}

A patch deprecates a certain core functionality
for a planned removal. See more information: [Deprecations](https://docs.typo3.org/permalink/t3contribute:deprecations)

**Mandatory sections:**

1.  **Description** \- why things had to be deprecated.
1.  **Impact** \- how will the change affect your installation.
1.  **Affected Installations** \- describe scenarios under which circumstances
    a TYPO3 install will be affected by this change.
1.  **Migration** \- provide instructions what needs to be done to get things
    working again. Explicitly mention if no migration is possible.

#### Features {#documenting-changelog-features}

A patch adds new functionality.

**Mandatory sections:**

1.  **Description** \- what can the new feature do.
1.  **Impact** \- how users are affected by this new feature.

#### Important Information {#documenting-changelog-important-information}

Anything that does not fit the other categories but is
important enough to require a Changelog entry.

1.  **Description** \- describe what is so important it needed an rst snippet

### Check Your `rst` File {#changelog-check-rst}

When your change is finished, you can run the following script to check that
your rst file is ok. The script will check all files in
`typo3/sysext/core/Documentation/Changelog`:

**shell command**

```shell
Build/Scripts/validateRstFiles.php
```

This script will check if the .rst files contain all mandatory tags that
are required for the Changelog. It will **not** do a reST syntax check.

In order to make sure that your file contains no syntax errors and will
be rendered correctly, do one or more of the following:

-   Check out [Coding guidelines for reST files](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Advanced/CodingGuidelines.html#format-rest-cgl).
-   [rendering the changelog locally](https://docs.typo3.org/permalink/t3contribute:render-the-changelog) with Docker or
    Podman and resolve all warnings.

## Policy for Changing the Main Documentation {#documentation-main}

Once a new TYPO3 release comes out, the main documentation (e.g. [TYPO3 Explained](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/Index.html#start),
[TCA Reference](https://docs.typo3.org/m/typo3/reference-tca/main/en-us/Index.html#start) etc.) must be updated.

The procedure is documented in [Apply Changelog entries to the docs](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Maintainers/Changelog.html#update-docs).

## Document System Extensions {#documenting-system-extensions}

Documentation for system extensions is maintained within a `Documentation`
directory in the respective system extension directory, e.g.
`typo3/sysext/form/Documentation`.

Not all system extensions have their own documentation. Some documentation
(e.g. for the system extension *core*) is maintained within the [TYPO3 Explained](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/Index.html#start).

If in doubt, ask in the **#typo3-cms-coredev** channel on Slack.

For starting a system extension from scratch, please see
[Use the init command to create the Documentation folder](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Howto/WritingDocForExtension/Index.html#how-to-start-docs-extension).

For an overview of the rendered documentation for system extensions, see
[System Extensions](https://docs.typo3.org/typo3cms/SystemExtensions/Index.html).

When you have made changes to the documentation, you can render
locally with docker to test your changes as described in
[rendering the changelog locally](https://docs.typo3.org/permalink/t3contribute:render-the-changelog).

## More Information {#more-information}

-   See [Documenting Changes](https://docs.typo3.org/c/typo3/cms-core/main/en-us/Changelog/Howto.html#documenting-changes)
    for more information on the Changelog
-   See [Extension scanner](https://docs.typo3.org/permalink/t3contribute:extension-scanner) in TYPO3 Explained