File structure

This page explains the general file structure of a TYPO3 documentation that can be rendered with the rendering toolchain. The toolchain itself uses a Sphinx theme for converting reStructuredText (reST) or Markdown to HTML.

General

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

  1. an index file in one of the following locations in weighted order:

    • Documentation/Index.rst

    • Documentation/index.rst

    • Documentation/Index.md

    • Documentation/index.md

    • README.rst

    • README.md

  2. and a theme configuration file under

    • Documentation/Settings.cfg.

Further conventions are:

  • reST files have the extension .rst.

  • Markdown files have the extension .md.

  • Included reST files have the extension .rst.txt.

  • Use CamelCase for directory and file names, for example: Documentation/GeneralConventions/FileStructure.rst.

These conventions pave the way for the full documentation and the single file documentation style, the first being preferred for several reasons.

Full documentation

This is the recommended setup and is commonly used in the official TYPO3 manuals and extension documentation.

This structure splits the documentation for the VCS host (README.rst) and the Sphinx theme (Documentation/) and allows full use of a continuously expanded set of custom content elements, like UML diagrams, which are only supported by the theme. This structure allows to add multiple pages to the documentation and build a full page tree.

The Settings.cfg configuration file allows you to set theme variables, i.e. the project title, release version and the like.

Of course, you can also use a README.md instead of a README.rst file as both markup languages are supported by the common VCS hosts.

.
├── README.rst
└── Documentation
    ├── genindex.rst
    ├── Includes.rst.txt
    ├── Index.rst
    ├── Settings.cfg
    ├── Sitemap.rst
    └── ..

Entry point: README.rst

Full documentation contains both a README.rst and a Documentation/Index.rst file. To avoid redundancy in both places, the README.rst in this case usually contains only a summary and links to all aspects of the project, i.e. the VCS repository, the published documentation and - if available - the TYPO3 Extension Repository (TER) page to guide the reader to the next steps. This could be for example:

Documentation/README.rst
<badges>

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

<abstract>

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

Badges

Point out interesting statistics of your extension or package in the badges placeholder, which should include the latest release version, the total and monthly download rate and the supported TYPO3 versions:

Documentation/README.rst
..  image:: https://poser.pugx.org/<package-name>/v/stable
    :alt: Latest Stable Version
    :target: https://extensions.typo3.org/extension/<extension-key>/

..  image:: https://img.shields.io/badge/TYPO3-11-orange.svg
    :alt: TYPO3 11
    :target: https://get.typo3.org/version/11

..  image:: https://poser.pugx.org/<package-name>/d/total
    :alt: Total Downloads
    :target: https://packagist.org/packages/<package-name>

..  image:: https://poser.pugx.org/<package-name>/d/monthly
    :alt: Monthly Downloads
    :target: https://packagist.org/packages/<package-name>

Remove this field if the project is no extension or package.

Project

The project placeholder contains the title of the project.

Common values are in the official TYPO3 manuals

  1. <Topic> Guide, e.g. "Installation and Upgrade Guide", for collections of articles on a specific topic

  2. <Topic> Reference, e.g. "TCA Reference", for a complete encyclopedia

  3. <Topic> Tutorial, e.g. "Getting Started Tutorial", for collections of tutorials on a specific topic

and in TYPO3 system and third-party extensions

  • TYPO3 extension <extension-key>, e.g. "TYPO3 extension ``extbase``" and "TYPO3 extension ``mask``".

Abstract

The abstract placeholder contains a short and precise description of the project with as many keywords as possible in as few sentences as possible. It helps the decision maker to quickly decide whether the project is worth considering and whether or not to read the full documentation. It should be aligned with the abstract of Index.rst and - if available - the description fields of ext_emconf.php and composer.json.

Startpage: Documentation/Index.rst

The documentation index file at Documentation/Index.rst is the starting 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. Besides these basic parts of this file, it includes - like any other reST file - the reST style file Includes.rst.txt:

Example with placeholders
.. include:: /Includes.rst.txt
..  _start:

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

:Extension key:
  <extension-key>

:Package name:
  <package-name>

:Version:
  |release|

:Language:
  en

:Author:
  <author>

:License:
  This document is published under the
  `Creative Commons BY 4.0 <https://creativecommons.org/licenses/by/4.0/>`__
  license.

:Rendered:
  |today|

----

<abstract>

----

**Table of Contents:**

<table-of-contents>

.. Meta Menu

<meta-menu>

All variables of the |name| pattern are automatically replaced by the Sphinx theme, partly from Settings.cfg, partly by internal calculations. For more information about all available variables, see the Replacements chapter of the Sphinx theme documentation.

The placeholders of pattern <name> must be replaced manually by the author of the documentation:

The startpage 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>`.

Project

The project placeholder corresponds best to the project property of Settings.cfg and - in case of a TYPO3 extension documentation - to the title field of ext_emconf.php.

Extension key

The extension-key placeholder contains the TYPO3 extension key in case of a TYPO3 extension documentation.

Remove this field if the project has no extension key.

Package name

The package-name placeholder contains the Composer package name of the project.

Remove this field if the project is no installable package.

Author

The author placeholder best matches the copyright holders in the Settings.cfg copyright property, since the authors of an open source project are also copyright holders. It is also a good place to mention initiators and outstanding contributors.

Abstract

The abstract placeholder contains a short and precise description of the project. It should follow the abstract of README.rst and - if available - the description fields of ext_emconf.php and composer.json.

Table of contents

The table-of-contents placeholder contains a rough table of contents (TOC), which - in combination with the abstract - should give the reader a quick overview. The TOC is built with the toctree directive as follows:

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

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

The maxdepth property limits the depth of the page tree and titlesonly specifies that only the titles of the pages are displayed, no other headings. Both should emphasize the nature of an overview.

The pages in the body of the directive are included in the TOC, and TOCs in those pages are resolved recursively. The documentation author must edit the list and provide a reST document at each of these file paths, interpreting the file paths as relative to the current file.

In general, the file hierarchy should match the menu hierarchy, and a page must be placed at either <page-name>.rst or <page-name>/Index.rst - the latter if subpages exist or are expected. For example, the page of the menu path "Usage > TYPO3 Backend > Shop Dashboard" should be stored at:

.
└── Documentation
    └── Usage
        └── Typo3Backend
            └── ShopDashboard.rst

or - if it has the subpage "Sell Widget" - at

.
└── Documentation
    └── Usage
        └── Typo3Backend
            └── ShopDashboard
                ├── Index.rst
                └── SellWidget.rst

Meta menu

The meta-menu placeholder builds a second menu that is not visible in the content area of the page, but only in the left sidebar (desktop) or toggle menu (mobile) - separate from the main menu. It contains links to functional pages, such as the Sitemap.rst and the genindex.rst, which do not provide content specific to this documentation, as follows:

..  toctree::
    :hidden:

    Sitemap
    genindex

Global rst settings: Documentation/Includes.rst.txt

Default style configurations are bundled in a central Documentation/Includes.rst.txt file and included at the beginning of each reST file. An absolute file path should be passed to use the same include statement on every page, regardless of which folder level the reST file is in:

..  include:: /Includes.rst.txt

Normally, the include directive is used with files with the extension .txt. To help your IDE associate reST syntax highlighting with the included files, we use the specific .rst.txt file extension.

Typical style configurations in TYPO3 documentation are definitions of custom text roles that allow inline code to be written. This is a typical Includes.rst.txt that provides text roles for most programming and markup languages used in a TYPO3 project:

Documentation/Includes.rst.txt
.. More information about this file:
.. https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/GeneralConventions/FileStructure.html#includes-rst-txt

.. ----------
.. text roles
.. ----------

.. role:: aspect(emphasis)
.. role:: bash(code)
.. role:: css(code)
.. role:: html(code)
.. role:: js(code)
.. role:: php(code)
.. role:: rst(code)
.. role:: sep(strong)
.. role:: sql(code)

.. role:: tsconfig(code)
  :class: typoscript

.. role:: typoscript(code)
.. role:: xml(code)
  :class: html

.. role:: yaml(code)

.. default-role:: code

.. ---------
.. highlight
.. ---------

.. By default, code blocks use PHP syntax highlighting

.. highlight:: php

The text roles that have been assigned a specific class mimic the syntax highlighting of another language. This is done to avoid confusing the reader with too many different colors. For example, XML inline code may be semantically marked with :xml:, but under the hood it uses the same highlighting as :html:.

Optional: Documentation/Sitemap.rst

The Sitemap.rst contains the sitemap of the documentation. It is an almost empty file that is automatically filled by the Sphinx template.

:template: sitemap.html

.. include:: /Includes.rst.txt

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

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

Optional: Automatic index: Documentation/genindex.rst

The genindex.rst shows a list of all indexes of the documentation pages. It is an almost empty file that is automatically filled by Sphinx. An index can be manually applied to each documentation location using the index directive. In addition, some content elements automatically generate indexes, such as the configuration values and PHP domain elements.

.. include:: /Includes.rst.txt

=====
Index
=====

.. Sphinx will insert here the general index automatically.

Settings: Documentation/Settings.cfg

This file contains the configuration for the Sphinx theme. The configuration values are used to fill placeholders in the theme. It consists of sections starting with a keyword in brackets, e.g. [general]: Make sure that all properties are in the correct section!

Documentation/Settings.cfg
# More information about this file:
# https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/GeneralConventions/FileStructure.html#settings-cfg

[general]

project     = <project>
version     = <version>
release     = <release>
copyright   = <copyright>

[html_theme_options]

# "Edit on GitHub" button
github_repository    = <github-repository>
github_branch        = <github-branch>

# Footer links
project_home         = <project-home>
project_contact      = <project-contact>
project_repository   = <project-repository>
project_issues       = <project-issues>
project_discussions  = <project-discussions>

use_opensearch       = <use-opensearch>

[intersphinx_mapping]

# Official TYPO3 manuals
# h2document     = https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/
# t3cheatsheets  = https://docs.typo3.org/m/typo3/docs-cheatsheets/main/en-us/
# t3contribute   = https://docs.typo3.org/m/typo3/guide-contributionworkflow/main/en-us/
# t3coreapi      = https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/
# t3docteam      = https://docs.typo3.org/m/typo3/team-t3docteam/main/en-us/
# t3editors      = https://docs.typo3.org/m/typo3/tutorial-editors/main/en-us/
# t3extbasebook  = https://docs.typo3.org/m/typo3/book-extbasefluid/main/en-us/
# t3extexample   = https://docs.typo3.org/m/typo3/guide-example-extension-manual/main/en-us/
# t3home         = https://docs.typo3.org/
# t3install      = https://docs.typo3.org/m/typo3/guide-installation/main/en-us/
# t3l10n         = https://docs.typo3.org/m/typo3/guide-frontendlocalization/main/en-us/
# t3sitepackage  = https://docs.typo3.org/m/typo3/tutorial-sitepackage/main/en-us/
# t3start        = https://docs.typo3.org/m/typo3/tutorial-getting-started/main/en-us/
# t3tca          = https://docs.typo3.org/m/typo3/reference-tca/main/en-us/
# t3translate    = https://docs.typo3.org/m/typo3/guide-frontendlocalization/main/en-us/
# t3tsconfig     = https://docs.typo3.org/m/typo3/reference-tsconfig/main/en-us/
# t3tsref        = https://docs.typo3.org/m/typo3/reference-typoscript/main/en-us/
# t3ts45         = https://docs.typo3.org/m/typo3/tutorial-typoscript-in-45-minutes/main/en-us/
# t3viewhelper   = https://docs.typo3.org/other/typo3/view-helper-reference/main/en-us/
# t3upgrade      = https://docs.typo3.org/m/typo3/guide-installation/main/en-us/

# TYPO3 system extensions
# ext_adminpanel     = https://docs.typo3.org/c/typo3/cms-adminpanel/main/en-us/
# ext_core           = https://docs.typo3.org/c/typo3/cms-core/main/en-us/
# ext_dashboard      = https://docs.typo3.org/c/typo3/cms-dashboard/main/en-us/
# ext_felogin        = https://docs.typo3.org/c/typo3/cms-felogin/main/en-us/
# ext_form           = https://docs.typo3.org/c/typo3/cms-form/main/en-us/
# ext_fsc            = https://docs.typo3.org/c/typo3/cms-fluid-styled-content/main/en-us/
# ext_impexp         = https://docs.typo3.org/c/typo3/cms-impexp/main/en-us/
# ext_indexed_search = https://docs.typo3.org/c/typo3/cms-indexed-search/main/en-us/
# ext_linkvalidator  = https://docs.typo3.org/c/typo3/cms-linkvalidator/main/en-us/
# ext_lowlevel       = https://docs.typo3.org/c/typo3/cms-lowlevel/main/en-us/
# ext_recycler       = https://docs.typo3.org/c/typo3/cms-recycler/main/en-us/
# ext_redirects      = https://docs.typo3.org/c/typo3/cms-redirects/main/en-us/
# ext_rte_ckeditor   = https://docs.typo3.org/c/typo3/cms-rte-ckeditor/main/en-us/
# ext_scheduler      = https://docs.typo3.org/c/typo3/cms-scheduler/main/en-us/
# ext_seo            = https://docs.typo3.org/c/typo3/cms-seo/main/en-us/
# ext_workspaces     = https://docs.typo3.org/c/typo3/cms-workspaces/main/en-us/

The placeholders of pattern <name> must be replaced manually by the author of the documentation, and commented or set empty if not required.

Project

The project property contains the title of the project and is displayed in the left sidebar (desktop) or the top (mobile) of the theme and in the title meta tag.

Common values are in the official TYPO3 manuals

  1. <Topic> Guide, e.g. "Frontend Localization Guide", for collections of articles on a specific topic

  2. <Topic> Reference, e.g. "TSconfig Reference", for a complete encyclopedia

  3. <Topic> Tutorial, e.g. "Editors Tutorial", for collections of tutorials on a specific topic

and in TYPO3 extension documentations

  • <Topic>, e.g. "Import / Export" or "Mask".

Version and release

The properties version and release both contain the version of the manual and mostly correspond to the version of the TYPO3 LTS or TYPO3 extension to which the documentation refers.

The version is shown below the title in the theme's release switch and in the title meta tag, the release is not shown currently - but it should be kept anyway to satisfy internal requirements.

Normally both properties are set to the same value, either

  • <major>.<minor>, e.g. "11.5", or

  • <major>.<minor>.<fix>, e.g. "11.5.1", or

  • main (development).

For the release switch entries, only the major and minor versions are considered.

GitHub workflow

The github_repository and github_branch properties must be set to provide the "Edit on GitHub" button, which allows the reader to jump from the currently viewed documentation directly to the associated GitHub repository and edit the page file.

If the project is hosted on GitHub and public contributions are desired, these properties should be set accordingly:

  1. <user>/<repository>, for example to "TYPO3-Documentation/TYPO3CMS-Reference-TCA" or "FriendsOfTYPO3/extension_builder".

  2. <branch>, for example on "main" or "10.x".

Use OpenSearch

If the use_opensearch property is set to the public URL of the documentation, Sphinx renders an OpenSearch description file of the documentation, which allows most browsers to treat the internal search of your documentation as a global search engine and include it in their search bar like any other search engine. This seems useful if your documentation is a large reference that is of high public interest and likely to be searched frequently by readers. Good examples of this are the PHP or TYPO3 Core references, for example "https://docs.typo3.org/m/typo3/reference-typoscript/main/en-us/", while the TYPO3 extension documentations probably are not.

Intersphinx mapping

The [intersphinx_mapping] section contains base URLs of public manuals for convenient and verified cross-referencing.

For example, if you uncomment the t3start mapping in the Settings.cfg above, the https://docs.typo3.org/m/typo3/tutorial-getting-started/main/en-us/Extensions/Management.html page can be referenced with

:doc:`t3start:Extensions/Management`

and the fragment #install-extension-with-composer on the same page with

:ref:`t3start:install-extension-with-composer`

The prerequisite is that the target manual is also compiled with Sphinx and provides an objects.inv file in the root of the documentation that contains all reference targets. Since this file is binary, the rendering toolchain provides a twin objects.inv.json file that allows the reader to easily look up reference targets. An example of this is this production objects.inv.json.

If a target reference becomes unavailable during documentation rendering, for example if it has been permanently removed, a warning is issued and stored in the toolchain log file at Documentation-GENERATED-temp/Result/project/0.0.0/_buildinfo/warnings.txt.

Single file documentation

This setup is not recommended, but can be handy for those who want to publish their documentation on docs.typo3.org and want to keep their mono README.rst documentation style for now.

This structure allows the author to minimize effort by maintaining a single documentation file that is interpreted simultaneously by the VCS host and the Sphinx theme. On the other hand, the author only has the reduced set of content elements supported by the former, rather than using the theme's rich selection of custom content elements.

Of course, you can also use a README.md instead of a README.rst file if you prefer its syntax.

.
├── README.rst
└── Documentation
    └── Settings.cfg

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

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

For more details, see the explanation of README.rst in the full documentation section.

Documentation/Settings.cfg

This file contains the configuration for the Sphinx theme. See the explanation of Settings.cfg in the full documentation section for more details.

Note

You can reduce the single file documentation even further by omitting the Settings.cfg - which is even less recommended, but works. All Sphinx theme variables will then fall back to their default values, e.g. the project title will then be "The Project's Title" and the release version "0.0.0".

Examples

These are some good examples of TYPO3 full and single file documentation in the wild.

Official TYPO3 manuals

Project

Links

TSconfig Reference (full)

README.rst | Settings.cfg | Index.rst | Includes.rst.txt | Read online

PHP application documentation

Project

Links

Surf (full)

README.md | Settings.cfg | Index.rst | Includes.txt | Read online

Tailor (single)

README.md | Read online

See also

Although it is possible to write every single line of a full documentation from scratch, the TYPO3 community provides tools to support you:

  • A sample manual is available to be immediately copied into your own extension.

  • The Extension Builder optionally generates a sample documentation together with the extension skeleton.

  • TYPO3 Core developers use the ReST Helper to kickoff a new TYPO3 changelog entry.