File structure

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

General

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

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
    └── ..
Copied!

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>`.
Copied!

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
Copied!

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
Copied!

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
Copied!

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
Copied!

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. [...]
Copied!

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.
Copied!

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.

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>
Copied!

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>}/`
Copied!
<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>/       |
Copied!