How to document an extension

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

To start a new manual, create the Documentation folder with the init command.

Rendering the documentation locally

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

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

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 documentation locally with Docker.

Use the init command to create the `Documentation` folder

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
    

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.

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 enter its name and path when prompted. This will regenerate ready to use documentation about configuration for you. If you have more than 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 the new documentation.

To publish your documentation to https://docs.typo3.org a webhook needs to be added 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 in channel #typo3-documentation.

Instructions for AI assistants

If you use an AI assistant to write the documentation, add a file AGENTS.md to the root of your extension, beside the composer.json. Most coding agents read this file by themselves when they start to work in the repository.

Keep the file short, and link to the pages of this guide instead of copying their rules. Do not put the file or a link to it into the Documentation folder, see File structure.

The following file is an example for the extension my_extension. Adapt the structure, the commands, and the commit rules to your repository:

AGENTS.md

# AGENTS.md — my_extension

## Repository structure

```
Classes/          # PHP code of the extension
Configuration/    # TCA, site set, and services
Documentation/    # the manual, reST source published to docs.typo3.org
Resources/        # templates, language files, and assets
composer.json     # the supported TYPO3 versions
```

## Commands

Render the manual and fail on every warning:

```bash
mkdir -p Documentation-GENERATED-temp
docker run --rm --pull always -v $(pwd):/project \
  ghcr.io/typo3-documentation/render-guides:latest \
  --config=Documentation --no-progress --minimal-test
```

Run it before every commit that changes `Documentation/`.

## Documentation rules

The manual follows the TYPO3 "How to document" guide. Read the rules
there instead of writing from memory:

- Writing style: https://docs.typo3.org/permalink/h2document:content-styleguide
- reST formatting: https://docs.typo3.org/permalink/h2document:format-rest-cgl
- Anchors: https://docs.typo3.org/permalink/h2document:link-anchor
- Links: https://docs.typo3.org/permalink/h2document:permalinks

If the skill `typo3-docs-writing` is installed, use it for every change
in `Documentation/`.

Rules of this repository:

- Check every fact about this extension against `Classes/` and
  `Configuration/` of the branch you work on.
- Check every fact about the TYPO3 Core against the lowest and the
  highest TYPO3 version that `composer.json` allows.
- Never remove an anchor, also not when you delete a section.

## Commits

- Never commit or push without being asked.
- Write the summary line in the imperative, and explain in the body
  why the change is needed.
- Add an `Assisted-by: <tool/model name> <contact>` trailer if you used
  AI assistance for more than a basic spelling or grammar check.

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

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.