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.
Table of Contents:
- Full documentation
- Single file documentation
In order for the documentation to be rendered, you need at least
- an index file in one of the following locations in weighted order:
- and a theme configuration file under
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.
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 └── ..
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:
<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>/
or as README.md alternatively:
<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>/ |
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:
.. 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>
or for the README.md alternatively:
[![Latest Stable Version](https://poser.pugx.org/<package-name>/v/stable)](https://extensions.typo3.org/extension/<extension-key>/) [![TYPO3 11](https://img.shields.io/badge/TYPO3-11-orange.svg?style=flat-square)](https://get.typo3.org/version/11) [![Total Downloads](https://poser.pugx.org/<package-name>/d/total)](https://packagist.org/packages/<package-name>) [![Monthly Downloads](https://poser.pugx.org/<package-name>/d/monthly)](https://packagist.org/packages/<package-name>)
Remove this field if the project is no extension or package.
The project placeholder contains the title of the project.
Common values are in the official TYPO3 manuals
<Topic> Guide, e.g. “Installation and Upgrade Guide”, for collections of articles on a specific topic
<Topic> Reference, e.g. “TCA Reference”, for a complete encyclopedia
<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``”.
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.
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:
.. include:: /Includes.rst.txt ========= <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
The placeholders of pattern
<name> must be replaced manually by the author of
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.
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.
The package-name placeholder contains the Composer package name of the project.
Remove this field if the project is no installable package.
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
- 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
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:
.. 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
:xml:, but under the hood it uses the same highlighting as
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.
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
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.
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!
# 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.
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
<Topic> Guide, e.g. “Frontend Localization Guide”, for collections of articles on a specific topic
<Topic> Reference, e.g. “TSconfig Reference”, for a complete encyclopedia
<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
For the release switch entries, only the major and minor versions are considered.
The copyright property contains the copyright claim of the project. It is displayed in the footer as “© Copyright <copyright>” and has in most use cases of the TYPO3 world the values:
since <creation-year> by the TYPO3 contributors, e.g. “since 1999 by the TYPO3 contributors” (official TYPO3 manuals and TYPO3 system extensions)
since <creation-year> by <vendor> & contributors, e.g. “since 1999 by dkd & contributors” (third-party TYPO3 extensions)
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:
<user>/<repository>, for example to “TYPO3-Documentation/TYPO3CMS-Reference-TCA” or “FriendsOfTYPO3/extension_builder”.
<branch>, for example on “main” or “10.x”.
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.
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,
page can be referenced with
and the fragment
#install-extension-with-composer on the same page with
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
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
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
<badges> ========= <project> ========= <abstract> Installation ============ .. Configuration ============= .. Usage ===== .. :Repository: https://<vcs-repository> :Read online: https://docs.typo3.org/p/<package-name>/main/en-us/ :TER: https://extensions.typo3.org/extension/<extension-key>/
or as README.md alternatively:
<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.
This file contains the configuration for the Sphinx theme. See the explanation of Settings.cfg in the full documentation section for more details.
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”.
These are some good examples of TYPO3 full and single file documentation in the wild.
|TSconfig Reference (full)||README.rst | Settings.cfg | Index.rst | Includes.rst.txt | Read online|
|Import / Export (full)||README.rst | Settings.cfg | Index.rst | Includes.rst.txt | Read online|
|Extension Builder (full)||README.rst | Settings.cfg | Index.rst | Includes.rst.txt | Read online|
|Make (single)||README.md | Settings.cfg | Read online|
|Surf (full)||README.md | Settings.cfg | Index.rst | Includes.txt | Read online|
|Tailor (single)||README.md | Read online|
Although it is possible to write every single line of a full documentation from scratch, the TYPO3 community provides tools to support you: