---
title: "How to document an extension"
manual: "How to Document"
version: "main"
permalink: "https://docs.typo3.org/permalink/h2document:write-doc-extensions-intro"
source: "Howto/WritingDocForExtension/Index.rst"
rendered: "2026-09-19T10:25:29+00:00"
---

# How to document an extension {#write-doc-extensions-intro}

This chapter explains how to write documentation for a new extension.

This guide uses the [example extension manual](https://github.com/TYPO3-Documentation/TYPO3CMS-Example-ExtensionManual)
as a template for starting out.

## Rendering the documentation locally {#write-doc-extensions-intro-rendering}

Use the following Docker command to render your documentation guide locally:

**Execute in extension root, the directory that contains your extensions composer.json**

```bash
docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --config=Documentation
```

Open the file saved to `Documentation-GENERATED-temp/Index.html` in a
browser of your choice.

See [Rendering the Documentation folder locally with Docker](https://docs.typo3.org/permalink/h2document:render-documentation-with-docker) for more information.

## Use the init command to create the `Documentation` folder {#how-to-start-docs-extension}

The following Docker command creates some basic documentation
including the required configuration file `Documentation/guides.xml`:

**Execute in extension root, the directory that contains your extension's composer.json**

```bash
docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest init
```

The command creates a folder `Documentation` in the directory it is called
from. This should be the root directory of your extension containing the
[composer.json](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/FileStructure/ComposerJson.html#files-composer-json).

Follow the interactive dialog. We suggest to use the option ReStructuredText (rst)
as this format provides the full power of the TYPO3 documentation theme. Using
Markdown (md) is an option for simple and quick one page documentation.

> [!NOTE]
> The first line of the guides.xml file can lead to rendering problems on the
> server, so it is best to delete it. The file should start with a `<guides`
> tag and not an `<?xml` tag.

If your extension offers a main [Site set](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/SiteHandling/SiteSets/Index.html#site-sets)
enter its name and path when prompted. This will regenerate ready to use
documentation about configuration for you. If you have more then one set you
can document the other sets manually. If you have no set, you need to write
the chapter yourself.

Make changes and try [rendering](https://docs.typo3.org/permalink/h2document:rendering-docs) the new documentation.

To publish your documentation to [https://docs.typo3.org](https://docs.typo3.org)
a [webhook needs to be added](https://docs.typo3.org/permalink/h2document:webhook) on GitHub, Bitbucket or GitLab.
A member of the Documentation Team has to approve your new documentation guide
for publishing. In case the Team has questions, please follow the thread
generated for your extension in the [TYPO3 slack organization](https://typo3.org/community/meet/chat-slack)
in channel [#typo3-documentation](https://typo3.slack.com/archives/C028JEPJL).

## Version numbers {#writing-doc-for-ext-start-version-numbers}

docs.typo3.org does no longer show three level version numbers in form of `Major.Minor.Patch`.
Only the first two levels are shown `Major.Minor`.

This reduces the amount of documentation while keeping relevant information,
as patch levels should not introduce breaking changes or new features.

## Supported branches {#supported-branches}

The rendering supports two branches within repositories:

-   **`main` / `master`**

    Should contain the current development state, used for upcoming release.
    Every push to these branches triggers a new rendering, available at
    `https://docs.typo3.org/p/<vendor>/<package>/main/en-us/`.

    Both branch names are supported, but result in the same URL.
    Please use `main`, `master` is only supported for backward compatibility.

-   **`documentation-draft`**

    Should contain a draft of the documentation.
    Every push to this branch triggers a new rendering, available at
    `https://docs.typo3.org/p/<vendor>/<package>/draft/en-us/`
    (same URL as main, except *main* is replaced by *draft*).

    This is not indexed by search engines. This branch can be used to test
    rendering before releasing a new version of an extension.

    In order to test a different rendering, remove the branch, and create it
    again.