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.
Table of Contents:
General¶
In order for the documentation to be rendered, you need at least
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
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:
<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>/
.. include:: /Includes.rst.txt
.. _start:
================================
Core documentation code examples
================================
:Language:
en
:Version:
|release|
:Description:
General TYPO3 CMS code examples. Used in particular for maintaining the official documentation.
:Keywords:
examples, tutorial, documentation
:Copyright:
2013-2021
:Author:
TYPO3 Documentation Team
:Email:
documentation@typo3.org
:License:
This document is published under the Open Content License
available from http://www.opencontent.org/opl.shtml
:Rendered:
|today|
.. toctree::
:titlesonly:
Introduction/Index
Users/Index
Maintainers/Index
.. include:: /Includes.rst.txt
.. _start:
===============
TYPO3 Dashboard
===============
:Extension key:
dashboard
:Package name:
typo3/cms-dashboard
:Version:
|release|
:Language:
en
:Author:
TYPO3 contributors
:License:
This document is published under the
`Open Content License <https://www.openhub.net/licenses/opl>`__.
:Rendered:
|today|
----
This TYPO3 backend module is used to configure and create backend widgets.
----
**Table of Contents:**
.. toctree::
:maxdepth: 2
:titlesonly:
Introduction/Index
Installation/Index
Editor/Index
Configuration/Index
Developer/Index
Widgets/Index
.. Meta Menu
.. toctree::
:hidden:
Sitemap
genindex
.. include:: /Includes.rst.txt
.. _start:
================================
TYPO3 - Getting Started Tutorial
================================
Welcome to Getting Started, this guide features an introduction to TYPO3 that
highlights some of its core concepts including the backend administrative
interface.
This guide also contains information on how to configure the host operating
system and features a detailed installation guide that explains how TYPO3 is
installed.
----
.. container:: row m-0 p-0
.. container:: col-md-6 pl-0 pr-3 py-3 m-0
.. container:: card px-0 h-100
.. rst-class:: card-header h3
.. rubric:: :ref:`Concepts <Concepts>`
.. container:: card-body
Written for new users, this chapter introduces some of TYPO3s core concepts including the backend, TYPO3s administration interface.
.. container:: col-md-6 pl-0 pr-3 py-3 m-0
.. container:: card px-0 h-100
.. rst-class:: card-header h3
.. rubric:: :ref:`System Requirements <System-Requirements>`
.. container:: card-body
System requirements for the host operation system, including its web server and database and how they should be configured prior to installation.
.. container:: col-md-6 pl-0 pr-3 py-3 m-0
.. container:: card px-0 h-100
.. rst-class:: card-header h3
.. rubric:: :ref:`Installation <Install>`
.. container:: card-body
The installation chapter provides detailed instructions about how to install TYPO3, it also contains information about how to deploy TYPO3 to a production environment.
.. container:: col-md-6 pl-0 pr-3 py-3 m-0
.. container:: card px-0 h-100
.. rst-class:: card-header h3
.. rubric:: :ref:`Setup <Setup>`
.. container:: card-body
Setup aims to guide you through the next steps post installation. Such as adding domains, setting up additional users and configuring languages.
.. container:: col-md-6 pl-0 pr-3 py-3 m-0
.. container:: card px-0 h-100
.. rst-class:: card-header h3
.. rubric:: :ref:`Troubleshooting <troubleshooting_index>`
.. container:: card-body
Troubleshoot common issues that can occur during installation. The Troubleshooting chapter covers both TYPO3 CMS and the host environment including the web server, database and PHP.
.. container:: col-md-6 pl-0 pr-3 py-3 m-0
.. container:: card px-0 h-100
.. rst-class:: card-header h3
.. rubric:: :ref:`Managing Backend Users <user-management>`
.. container:: card-body
Learn how to create users and configure their backend privileges.
.. container:: col-md-6 pl-0 pr-3 py-3 m-0
.. container:: card px-0 h-100
.. rst-class:: card-header h3
.. rubric:: :ref:`Working With Extensions <extensions_index>`
.. container:: card-body
Discover how third-party extensions are installed and managed using Composer.
.. container:: col-md-6 pl-0 pr-3 py-3 m-0
.. container:: card px-0 h-100
.. rst-class:: card-header h3
.. rubric:: :ref:`The Introduction Package <introductionpackage_index>`
.. container:: card-body
The Introduction Package is a great place to start if you are looking to test drive TYPO3 and see a prebuilt site that contains
a range of example page templates and content.
.. container:: col-md-6 pl-0 pr-3 py-3 m-0
.. container:: card px-0 h-100
.. rst-class:: card-header h3
.. rubric:: :ref:`Next Steps <next-steps>`
.. container:: card-body
Next Steps provides an overview of tasks that can be carried out once TYPO3 is installed, such as creating templates and adding content.
.. Table of Contents
.. toctree::
:hidden:
:titlesonly:
Concepts/Index
SystemRequirements/Index
Installation/Index
Setup/Index
Troubleshooting/Index
Extensions/Index
UserManagement/Index
IntroductionPackage/Index
NextSteps/Index
----
:Version:
|release|
:Language:
en
:Author:
TYPO3 contributors
:License:
This document is published under the
`Open Publication License <https://www.opencontent.org/openpub/>`__.
:Rendered:
|today|
.. Meta Menu
.. toctree::
:hidden:
Sitemap
genindex
<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>/ |
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:
.. 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>
[](https://extensions.typo3.org/extension/<extension-key>/)
[](https://get.typo3.org/version/11)
[](https://packagist.org/packages/<package-name>)
[](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
<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``".
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
:
.. 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>
.. include:: /Includes.rst.txt
.. _start:
================================
Core documentation code examples
================================
:Language:
en
:Version:
|release|
:Description:
General TYPO3 CMS code examples. Used in particular for maintaining the official documentation.
:Keywords:
examples, tutorial, documentation
:Copyright:
2013-2021
:Author:
TYPO3 Documentation Team
:Email:
documentation@typo3.org
:License:
This document is published under the Open Content License
available from http://www.opencontent.org/opl.shtml
:Rendered:
|today|
.. toctree::
:titlesonly:
Introduction/Index
Users/Index
Maintainers/Index
.. include:: /Includes.rst.txt
.. _start:
===============
TYPO3 Dashboard
===============
:Extension key:
dashboard
:Package name:
typo3/cms-dashboard
:Version:
|release|
:Language:
en
:Author:
TYPO3 contributors
:License:
This document is published under the
`Open Content License <https://www.openhub.net/licenses/opl>`__.
:Rendered:
|today|
----
This TYPO3 backend module is used to configure and create backend widgets.
----
**Table of Contents:**
.. toctree::
:maxdepth: 2
:titlesonly:
Introduction/Index
Installation/Index
Editor/Index
Configuration/Index
Developer/Index
Widgets/Index
.. Meta Menu
.. toctree::
:hidden:
Sitemap
genindex
.. include:: /Includes.rst.txt
.. _start:
================================
TYPO3 - Getting Started Tutorial
================================
Welcome to Getting Started, this guide features an introduction to TYPO3 that
highlights some of its core concepts including the backend administrative
interface.
This guide also contains information on how to configure the host operating
system and features a detailed installation guide that explains how TYPO3 is
installed.
----
.. container:: row m-0 p-0
.. container:: col-md-6 pl-0 pr-3 py-3 m-0
.. container:: card px-0 h-100
.. rst-class:: card-header h3
.. rubric:: :ref:`Concepts <Concepts>`
.. container:: card-body
Written for new users, this chapter introduces some of TYPO3s core concepts including the backend, TYPO3s administration interface.
.. container:: col-md-6 pl-0 pr-3 py-3 m-0
.. container:: card px-0 h-100
.. rst-class:: card-header h3
.. rubric:: :ref:`System Requirements <System-Requirements>`
.. container:: card-body
System requirements for the host operation system, including its web server and database and how they should be configured prior to installation.
.. container:: col-md-6 pl-0 pr-3 py-3 m-0
.. container:: card px-0 h-100
.. rst-class:: card-header h3
.. rubric:: :ref:`Installation <Install>`
.. container:: card-body
The installation chapter provides detailed instructions about how to install TYPO3, it also contains information about how to deploy TYPO3 to a production environment.
.. container:: col-md-6 pl-0 pr-3 py-3 m-0
.. container:: card px-0 h-100
.. rst-class:: card-header h3
.. rubric:: :ref:`Setup <Setup>`
.. container:: card-body
Setup aims to guide you through the next steps post installation. Such as adding domains, setting up additional users and configuring languages.
.. container:: col-md-6 pl-0 pr-3 py-3 m-0
.. container:: card px-0 h-100
.. rst-class:: card-header h3
.. rubric:: :ref:`Troubleshooting <troubleshooting_index>`
.. container:: card-body
Troubleshoot common issues that can occur during installation. The Troubleshooting chapter covers both TYPO3 CMS and the host environment including the web server, database and PHP.
.. container:: col-md-6 pl-0 pr-3 py-3 m-0
.. container:: card px-0 h-100
.. rst-class:: card-header h3
.. rubric:: :ref:`Managing Backend Users <user-management>`
.. container:: card-body
Learn how to create users and configure their backend privileges.
.. container:: col-md-6 pl-0 pr-3 py-3 m-0
.. container:: card px-0 h-100
.. rst-class:: card-header h3
.. rubric:: :ref:`Working With Extensions <extensions_index>`
.. container:: card-body
Discover how third-party extensions are installed and managed using Composer.
.. container:: col-md-6 pl-0 pr-3 py-3 m-0
.. container:: card px-0 h-100
.. rst-class:: card-header h3
.. rubric:: :ref:`The Introduction Package <introductionpackage_index>`
.. container:: card-body
The Introduction Package is a great place to start if you are looking to test drive TYPO3 and see a prebuilt site that contains
a range of example page templates and content.
.. container:: col-md-6 pl-0 pr-3 py-3 m-0
.. container:: card px-0 h-100
.. rst-class:: card-header h3
.. rubric:: :ref:`Next Steps <next-steps>`
.. container:: card-body
Next Steps provides an overview of tasks that can be carried out once TYPO3 is installed, such as creating templates and adding content.
.. Table of Contents
.. toctree::
:hidden:
:titlesonly:
Concepts/Index
SystemRequirements/Index
Installation/Index
Setup/Index
Troubleshooting/Index
Extensions/Index
UserManagement/Index
IntroductionPackage/Index
NextSteps/Index
----
:Version:
|release|
:Language:
en
:Author:
TYPO3 contributors
:License:
This document is published under the
`Open Publication License <https://www.opencontent.org/openpub/>`__.
:Rendered:
|today|
.. Meta Menu
.. toctree::
:hidden:
Sitemap
genindex
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
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:
.. 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
.. This is 'Includes.txt'. It is included at the very top of each and
every ReST source file in THIS documentation project (= manual).
.. role:: aspect(emphasis)
.. role:: html(code)
.. role:: js(code)
.. role:: php(code)
.. role:: pn(emphasis)
.. role:: sep(strong)
.. role:: sql(code)
.. role:: typoscript(code)
.. role:: xml(code)
.. role:: yaml(code)
.. role:: ts(typoscript)
:class: typoscript
.. default-role:: code
.. highlight:: php
.. 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:: 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 YAML syntax highlighting
.. highlight:: yaml
.. 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:: 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!
# 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.
[general]
project = Core documentation code examples
version = master (development)
release = master (development)
copyright = since 1999 by the TYPO3 Documentation Team
t3author = TYPO3 Documentation Team
copyright = since 2000 by the TYPO3 Documentation Team
description = …
[html_theme_options]
github_branch = master
github_repository = TYPO3-Documentation/t3docs-examples
project_contact =
project_discussions =
project_home = https://github.com/TYPO3-Documentation/t3docs-examples
project_issues = https://github.com/TYPO3-Documentation/t3docs-examples/issues
project_repository = https://github.com/TYPO3-Documentation/t3docs-examples
[extlinks]
issue = https://github.com/TYPO3-Documentation/t3docs-examples/issues/%s | Issue #
[intersphinx_mapping]
t3coreapi = https://docs.typo3.org/m/typo3/reference-coreapi/master/en-us/
t3extbasebook = https://docs.typo3.org/m/typo3/book-extbasefluid/master/en-us/
t3tca = https://docs.typo3.org/m/typo3/reference-tca/master/en-us/
t3tsref = https://docs.typo3.org/m/typo3/reference-typoscript/master/en-us/
# # TYPO3 official docs
# h2document = https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/
# t3contribute = https://docs.typo3.org/m/typo3/guide-contributionworkflow/master/en-us/
# t3editors = https://docs.typo3.org/m/typo3/tutorial-editors/master/en-us/
# t3install = https://docs.typo3.org/m/typo3/guide-installation/master/en-us/
# t3sitepackage = https://docs.typo3.org/m/typo3/tutorial-sitepackage/master/en-us/
# t3start = https://docs.typo3.org/m/typo3/tutorial-getting-started/master/en-us/
# t3ts45 = https://docs.typo3.org/m/typo3/tutorial-typoscript-in-45-minutes/master/en-us/
# t3tsconfig = https://docs.typo3.org/m/typo3/reference-tsconfig/master/en-us/
# t3viewhelper = https://docs.typo3.org/other/typo3/view-helper-reference/master/en-us/
#
# # TYPO3 system extensions
# ckedit = https://docs.typo3.org/c/typo3/cms-rte-ckeditor/master/en-us/
# form = https://docs.typo3.org/c/typo3/cms-form/master/en-us/
# fsc = https://docs.typo3.org/c/typo3/cms-fluid-styled-content/master/en-us/
# sched = https://docs.typo3.org/c/typo3/cms-scheduler/master/en-us/
# t3core = https://docs.typo3.org/c/typo3/cms-core/master/en-us/
# t3dashboard = https://docs.typo3.org/c/typo3/cms-dashboard/master/en-us/
# workspaces = https://docs.typo3.org/c/typo3/cms-workspaces/master/en-us/
# 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 = Dashboard
version = main (development)
release = main (development)
copyright = since 2020 by the TYPO3 contributors
[html_theme_options]
# "Edit on GitHub" button
github_repository = typo3/typo3
github_branch = main
path_to_documentation_dir = typo3/sysext/dashboard/Documentation
# Footer links
project_home = https://extensions.typo3.org/extension/dashboard/
project_contact = https://typo3.slack.com/archives/C025BQLFA
project_repository = https://github.com/typo3/typo3
project_issues = https://forge.typo3.org/projects/typo3cms-core/issues
project_discussions =
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/
# t3templating = https://docs.typo3.org/m/typo3/tutorial-templating/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_indexed_search = https://docs.typo3.org/c/typo3/cms-indexed-search/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/
# 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 = Getting Started
version = main (development)
release = main (development)
copyright = since 2012 by the TYPO3 contributors
[html_theme_options]
# "Edit on GitHub" button
github_repository = TYPO3-Documentation/TYPO3CMS-Tutorial-GettingStarted
github_branch = main
# Footer links
project_home = https://docs.typo3.org/m/typo3/tutorial-getting-started/main/en-us/
project_contact = https://typo3.slack.com/archives/C028JEPJL
project_repository = https://github.com/TYPO3-Documentation/TYPO3CMS-Tutorial-GettingStarted
project_issues = https://github.com/TYPO3-Documentation/TYPO3CMS-Tutorial-GettingStarted/issues
project_discussions =
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_indexed_search = https://docs.typo3.org/c/typo3/cms-indexed-search/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/
ext_surf = https://docs.typo3.org/other/typo3/surf/main/en-us/
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
<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", ormain (development)
.
For the release switch entries, only the major and minor versions are considered.
Copyright¶
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
, for example "since 1999 by the TYPO3 contributors" (official TYPO3 manuals and TYPO3 system extensions)since <creation-year> by <vendor> & contributors
, for example "since 1999 by dkd & contributors" (third-party TYPO3 extensions)
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:
<user>/<repository>
, for example to "TYPO3-Documentation/TYPO3CMS-Reference-TCA" or "FriendsOfTYPO3/extension_builder".<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
<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>/ |
<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>/ |
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 |
TYPO3 system extension documentation¶
Project |
Links |
---|---|
Import / Export (full) |
README.rst | Settings.cfg | Index.rst | Includes.rst.txt | Read online |
TYPO3 third-party extension documentation¶
Project |
Links |
---|---|
Extension Builder (full) |
README.rst | Settings.cfg | Index.rst | Includes.rst.txt | Read online |
Make (single) |
PHP application documentation¶
Project |
Links |
---|---|
Surf (full) |
README.md | Settings.cfg | Index.rst | Includes.txt | Read online |
Tailor (single) |
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.