File structure

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

Table of Contents:

Prerequisites for rendering documentation to docs.typo3.org

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

A valid composer.json

And one of the following files:

Documentation/Index.rst (Full documentation in reST)
Documentation/Index.md (Full documentation in reST markdown)
README.rst (Single file documentation (README))
README.md (Single file documentation (README))

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 shall have a file named Index.rst it is used as fallback if a page is not found during switching versions.
Code examples to be included should start with an underscore, for example _Services.yaml.

Full documentation in reST

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>

Full documentation in reST markdown

The TYPO3 documentation rendering pipeline supports rendering of CommonMark Markdown plus a few additional constructs like tables.

The main entry point for Markdown documentation must be Documentation/Index.md. Each folder in the Documentation directory should contain a file called Index.md if it contains Markdown at all.

<?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"
        input-format="md"
        index-name="Index"
        automatic-menu="true"
>
    <project title="My Extension" />
    <extension
            class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
            edit-on-github="myvendor/my-extension"
            edit-on-github-branch="main"
            interlink-shortcode="myvendor/my-extension"
            project-home="https://github.com/myvendor/my-extension"
            project-issues="https://github.com/myvendor/my-extension/issues"
            project-repository="https://github.com/myvendor/my-extension"
            typo3-core-preferred="stable"
    />
</guides>

Lines 6-8 are different from reST documents.

line 6: Set the input format to Markdown (md)
line 7-8: Automatically create a menu with all Markdown files and folders found. Folders must have a Index.md to be added.

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.

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>/       |