Note

This version of the guide covers the new PHP-based rendering of Documentation with the TYPO3 Documentation theme.

If the project you are looking at has a file Documentation/guides.xml it is using the new rendering.

Otherwise, consider to migrate the Documentation or head over to the legacy version of this guide: How to document, Sphinx based.

File structure

This page explains the general file structure of a TYPO3 documentation that can be rendered with the rendering toolchain.

Table of Contents:

General

In order for the documentation to be rendered, you need at least

A valid composer.json
A documentation entry point either for a multi-page manual or for the rendering of a single README file.

The following rules are mandatory or your documentation will not render:

reST files MUST have the extension :file:`.rst'.
Markdown files MUST have the extension :file:`.md'.

Further conventions are:

Included reST files SHOULD have the extension .rst.txt.
Use CamelCase for directory and file names, for example: Documentation/GeneralConventions/FileStructure.rst.
Each directory SHOULD have a file named Index.rst it is used as fallback if a page is not found during switching versions.

Full documentation

To render a complete documentation manual you need a folder called Documentation with at least a reStructured Text file as entry point named DocumentationIndex.rst and a configuration file called Documentationguides.xml. Add more files as needed.

You can keep a README.md or README.rst file with basic information and a link to the published manual in the root folder of the extension. These files will be commonly displayed on GitHub and GitLab.

.
├── composer.json
├── README.rst
└── Documentation
    ├── guides.xml
    ├── Index.rst
    ├── Sitemap.rst
    └── ..

Start page: `Documentation/Index.rst`

The documentation start page (Documentation/Index.rst) is the entry point of the main documentation. It usually contains general information about the manual, a summary of its purpose and a table of contents that refers to further pages.

The start page should contain an anchor target .. _start: above its document title. This way you can link to a documents start page by:

See :ref:`TYPO3 Explained <t3coreapi:start>`.

If your manual has more pages then this start page it must contain a table of content directive called .. toctree::. The toctree on the start page defines which pages will be displayed in main navigation of the rendered manual.

Configure the menu - the toctree

The toctree on the start page can be hidden, it then only influences the main navigation:

..  toctree::
    :hidden:

    Introduction/Index
    Installation/Index
    Configuration/Index
    Usage/Index
    Contribution/Index

Or it can be inserted visibly into the start page to provide an entry point:

..  toctree::
    :maxdepth: 2
    :titlesonly:

    Introduction/Index
    Installation/Index
    Configuration/Index
    Usage/Index
    Contribution/Index

For large pages it is advisable to limit the number of menu levels that will be displayed on the startpage by setting :maxdepth:. This will not limit the level of pages displayed in the main navigation.

For more information on possible options on the toctree directive see chapter Toctrees in the reST reference.

It is possible to use more then one toctree directive on the start page. Each toctree should have a :caption: in this case.

The main navigation will then be divided into sections labeled by those captions. The menu of the manual you are currently reading is an example for that:

Documentation/Index.rst

..  toctree::
    :hidden:
    :caption: Basics

    About
    HowToGetHelp
    ...

.. toctree::
    :hidden:
    :caption: Howtos

    WritingContent/Index
    WritingDocForExtension/Index
    ...

..  toctree::
    :hidden:
    :caption: Advanced

    HowToAddTranslation/Index
    GeneralConventions/HowToUpdateDocs
    GeneralConventions/ReviewInformation

..  toctree::
    :hidden:
    :caption: Maintainers

    Maintainers/Index

Optional: `Documentation/Includes.rst.txt`

The Includes.rst.txt is optional for Extension documentation. We use it by convention in all official documentation.

By default it only contains a comment:

Documentation/Includes.rst.txt

..  You can put central messages to display on all pages here

In the official documentation we use it to mark outdated and eLTS versions:

Documentation/Includes.rst.txt

..  You can put central messages to display on all pages here

..  attention::
    TYPO3 v10 has reached end-of-life as of April 30th 2023 and
    is no longer being maintained. [...]

Before migration to the new rendering it also contained configuration settings. All those have been moved to the guides.xml or have been replaced by defaults in our theme implementation.

Optional: `Documentation/Sitemap.rst`

The Sitemap.rst contains the sitemap of the documentation. It is an almost empty file that is automatically filled during rendering.

:template: sitemap.html

.. include:: /Includes.rst.txt

=======
Sitemap
=======

.. The sitemap.html template will insert here the page tree automatically.

Settings: `Documentation/guides.xml`

This file contains the metadata and configuration for the rendering with the TYPO3 theme.

Read more about the Configuration of the rendering - guides.xml.

Hint

If you are migrating from the legacy Sphinx-based rendering and still have a Documentation/Settings.cfg you can use an automatic migration tool to migrate the settings.cfg into a guides.xml.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<guides xmlns="https://www.phpdoc.org/guides" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://www.phpdoc.org/guides ../vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
        links-are-relative="true"
        default-code-language="php"
>
    <extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
               project-home="https://extensions.typo3.org/extension/news/"
               project-contact="https://typo3.slack.com/archives/C03TG7QJT"
               project-repository="https://github.com/georgringer/news"
               project-issues="https://github.com/georgringer/news/issues"
               project-discussions="https://github.com/georgringer/news/discussions"
               edit-on-github-branch="main"
               edit-on-github="georgringer/news"
               typo3-core-preferred="11.5"
               interlink-shortcode="georgringer/news"
    />
    <project title="News system"
             version="local"
             copyright="since 2010 by Georg Ringer &amp; Contributors"
    />
    <inventory id="t3extbasebook" url="https://docs.typo3.org/m/typo3/book-extbasefluid/10.4/en-us/"/>
</guides>

Single file documentation (README)

For third-party TYPO3 extensions that do not require extended documentation you can also publish a README.rst or README.md to https://docs.typo3.org/

For this workflow the README(.rst/.md) MUST be situated in the extension's root folder. The :file:`Documentation/' folder can then be omitted.

`README.rst`

For single file documentation, the README.rst contains the entire documentation.

This should also contain links to all aspects of the project to guide the reader to the next steps, for example

Documentation/README.rst

<badges>

=========
<project>
=========

<abstract>

Installation
============
..

Configuration
=============
..

Usage
======
..

..  csv-table::
    :header: "", "URL"

    **Repository:**,        :samp:`https://{<vcs-repository>}`
    **Read online:**,       :samp:`https://docs.typo3.org/p/{<package-name>}/main/en-us/`
    **TER:**,               :samp:`https://extensions.typo3.org/extension/{<extension-key>}/`

<badges>

# <project>

<abstract>

|                  | URL                                                           |
|------------------|---------------------------------------------------------------|
| **Repository:**  | https://<vcs-repository>                                      |
| **Read online:** | https://docs.typo3.org/p/<package-name>/main/en-us/           |
| **TER:**         | https://extensions.typo3.org/extension/<extension-key>/       |

File structure

General

Full documentation

Start page: Documentation/Index.rst

Configure the menu - the toctree

Optional: Documentation/Includes.rst.txt

Optional: Documentation/Sitemap.rst

Settings: Documentation/guides.xml