Directories and file names¶
If the documentation follows these conventions, the documentation rendering toolchain automatically detects the documentation and renders it correctly on the documentation server.
For documentation to be rendered, you need at least:
- (required) composer.json in project root. As of May 29, 2019, this is now mandatory!
- (required) a “start file”,
usually
Documentation/Index.rst
or one of the alternatives, such asREADME.rst
. - (required) Documentation/Settings.cfg
Hint
For some example texts, please see Examples.
The other files listed here may not be required, but are recommended.
Further conventions:
- reStructueredText files have ending .rst
- Markdown files have ending .md
- Included files have ending .rst.txt
- Use CamelCase for directories and .rst file names (e.g.
Index.rst
,ExtensionArchitecture.rst
).
Minimal setup (“classic”)¶
This is the recommended setup. It is used by the official documentation.
.
├── composer.json
└── Documentation
├── Index.rst
└── Settings.cfg
└── ...
For alternative start page (e.g. README.rst
or README.md
),
see “start file”.
composer.json¶
– required
The composer.json
file must be valid and contain TYPO3 CMS as
requirement. In order to validate the composer.json
, the
following command can be used within the folder containing the file:
composer validate
The following two examples demonstrate the minimum content for different supported TYPO3 versions.
Example for TYPO3 CMS > 8.7.7:
{
"name": "vendor/package-key",
"type": "typo3-cms-extension",
"description": "An example extension",
"license": "GPL-2.0-or-later",
"require": {
"typo3/cms-core": "^8.7.8"
},
"extra": {
"typo3/cms": {
"extension-key": "extension_key"
}
}
}
For extensions supporting TYPO3 versions lower then 8.7.7, typo3/cms
is
required as dependency instead of typo3/cms-core
:
{
"name": "vendor/package-key",
"type": "typo3-cms-extension",
"description": "An example extension",
"license": "GPL-2.0-or-later",
"require": {
"typo3/cms": "^7.6"
},
"extra": {
"typo3/cms": {
"extension-key": "extension_key"
}
}
}
The extra
section can be used to provide an TYPO3 extension_key
for the
package. This will be used when found. If not provided, the package-key
will
be used, where all -
get replaced by _
, to follow TYPO3 and packagist
conventions.
Start file¶
– required
The recommended start file is Documentation/Index.rst
. This is what is used for
official manuals.
Use Index.rst in this manual as an example.
The following is also supported (in this priority):
Documentation/Index.rst
Documentation/index.rst
Documentation/Index.md
Documentation/index.md
README.rst
README.md
If none of these files exist, no documentation will be rendered.
The files ending in .md contain Markdown, the files ending in .rst contain reStructuredText (reST).
For information about what texts can be on the start page, please see Start page.
Tip
Official manuals often contain both: README.rst
and Documentation/Index.rst
.
Because Documentation/Index.rst
has higher priority, this will be used as start
page. The additional README.rst is used as an “about file”.
Warning
If you use a single file solution (everything in one file without toctree), there is still an open issue concerning the menu. See the workaround.
Example - “classic” with toctree¶
A similar structure is used by the official documentation.
Files¶
.
├── ...
├── composer.json
└── Documentation
├── Index.rst
├── Settings.cfg
└── Introduction.rst
└── Configuration.rst
Content¶
Index.rst:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | .. include:: /Includes.rst.txt
=====
Title
=====
some text
.. toctree::
:hidden:
Introduction
Configuration
|
- line 1: every .rst file should include /Includes.rst.txt
- line 3-5: the header
- line 10-14: the toctree defines which other pages will be included
and combined. The menu is generated from all combined files (recursively).
Here we include the files
Introduction.rst
,Configuration.rst
Introduction.rst:
.. include:: /Includes.rst.txt
============
Introduction
============
some text
A subsection
============
Alternatively, the introduction file may include a toctree as well.
Example - single file¶
This uses an alternative start file README.rst
on the top level,
instead of Documentation/Index.rst
.
This may be better suited for extensions.
Files¶
.
├── ...
├── README.rst
└── Documentation
├── Settings.cfg
└── ...
Content¶
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | =====
Title
=====
Introduction
============
... text with introduction ...
Configuration
=============
... text with configuration ...
|
- line 1: every .rst file should include /Includes.rst.txt
- line 3-5: the title
- Here, all text is contained in one file.
Workaround for single file¶
Warning
If you use a single file solution (everything in one file), there is still an open issue concerning the menu.
Currently, there is a workaround: Remove the title:
Introduction
============
... text with introduction ...
Configuration
=============
... text with configuration ...
Settings.cfg¶
– required
Documentation/Settings.cfg
Important
This file must be adapted for the manual.
- Use Settings.cfg in this project as an up-to-date example for an official manual!
- Use the file in TYPO3CMS-Example-ExtensionManual as an up-to-date example for an extension manual!
The file consists of sections, which start with a keyword in brackets, such as [general]
.
Make sure that all directives exist in the correct section.
Intersphinx mapping¶
Settings.cfg
contains start urls for the Cross referencing (:ref:) linking mechanism.
Every manual used for cross referencing must be uncommented in the section intersphinx_mapping
.
This is an up-to-date list of mappings commonly used:
[intersphinx_mapping]
# ----------------
# official manuals
# ----------------
# 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/
# t3coreapi = https://docs.typo3.org/m/typo3/reference-coreapi/master/en-us/
# t3docteam = https://docs.typo3.org/m/typo3/team-t3docteam/master/en-us/
# t3editors = https://docs.typo3.org/m/typo3/tutorial-editors/master/en-us/
# t3extbase = https://docs.typo3.org/m/typo3/guide-extbasefluid/master/en-us/
# t3extbasebook = https://docs.typo3.org/m/typo3/book-extbasefluid/master/en-us/
# t3install = https://docs.typo3.org/m/typo3/guide-installation/master/en-us/
# t3l10n = https://docs.typo3.org/m/typo3/guide-frontendlocalization/master/en-us/
# t3start = https://docs.typo3.org/m/typo3/tutorial-getting-started/master/en-us/
# t3sitepackage = https://docs.typo3.org/m/typo3/tutorial-sitepackage/master/en-us/
# t3tca = https://docs.typo3.org/m/typo3/reference-tca/master/en-us/
# t3templating = https://docs.typo3.org/m/typo3/tutorial-templating/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/
# t3tsref = https://docs.typo3.org/m/typo3/reference-typoscript/master/en-us/
# t3vhref = https://docs.typo3.org/other/typo3/view-helper-reference/master/en-us/
# ----------------
# system extension
# ----------------
# ckedit = https://docs.typo3.org/c/typo3/cms-rte-ckeditor/master/en-us/
# core = https://docs.typo3.org/c/typo3/cms-core/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/
Tip
Uncomment only the manuals to which you will be linking to in your manual For example, change:
# t3tsref = https://docs.typo3.org/m/typo3/reference-typoscript/master/en-us/
to:
t3tsref = https://docs.typo3.org/m/typo3/reference-typoscript/master/en-us/
Example¶
This is Settings.cfg
for this manual.
# Sphinx setup file for this project
#
# This document lives here:
# https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument/blob/master/Documentation/Settings.cfg
# See sample file:
# https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument/blob/master/Documentation/Settings.cfg
# Documentation:
# https://docs.typo3.org/typo3cms/HowToDocument/GeneralConventions/DirectoryFilenames.html#settings-cfg
[general]
# .................................................................................
# ... (required) title (displayed in left sidebar (desktop) or top panel (mobile)
# .................................................................................
project = Writing Documentation
# .................................................................................
# ... (recommended) version, displayed next to title (desktop) and in <meta name="book-version"
# ... Set during rendering based on rendered version
# .................................................................................
release = 2.0.0
# .................................................................................
# ... (recommended) displayed in footer
# .................................................................................
copyright = since 1999 by the TYPO3 Documentation Team
[html_theme_options]
# .................................................................................
# ... (recommended) to get the "Edit on GitHub Button"
# .................................................................................
github_branch = master
github_repository = TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument
# .................................................................................
# ... (recommended) Fill in values to get links in the footer of rendered page
# .................................................................................
project_contact = https://typo3.org/community/teams/documentation/#c9886
project_discussions =
project_home = https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument
project_issues = https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument/issues
project_repository = https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument
[intersphinx_mapping]
# .................................................................................
# for cross-referencing across manuals (intersphinx) with :ref:
#
# You must uncomment all manuals you use in your cross-references
#
# Example usage:
# :ref:`t3contribute:start` will link to start page of Contribution Guide
# .................................................................................
# ----------------
# official manuals
# ----------------
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/
t3coreapi = https://docs.typo3.org/m/typo3/reference-coreapi/master/en-us/
t3docteam = https://docs.typo3.org/m/typo3/team-t3docteam/master/en-us/
# t3editors = https://docs.typo3.org/m/typo3/tutorial-editors/master/en-us/
# t3extbase = https://docs.typo3.org/m/typo3/guide-extbasefluid/master/en-us/
t3extbasebook = https://docs.typo3.org/m/typo3/book-extbasefluid/master/en-us/
t3install = https://docs.typo3.org/m/typo3/guide-installation/master/en-us/
# t3l10n = https://docs.typo3.org/m/typo3/guide-frontendlocalization/master/en-us/
t3start = https://docs.typo3.org/m/typo3/tutorial-getting-started/master/en-us/
t3sitepackage = https://docs.typo3.org/m/typo3/tutorial-sitepackage/master/en-us/
t3tca = https://docs.typo3.org/m/typo3/reference-tca/master/en-us/
# t3templating = https://docs.typo3.org/m/typo3/tutorial-templating/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/
t3tsref = https://docs.typo3.org/m/typo3/reference-typoscript/master/en-us/
# t3vhref = https://docs.typo3.org/other/typo3/view-helper-reference/master/en-us/
# ----------------
# system extension
# ----------------
# ckedit = https://docs.typo3.org/c/typo3/cms-rte-ckeditor/master/en-us/
t3core = https://docs.typo3.org/c/typo3/cms-core/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/
[extensions]
# .................................................................................
# ; Add to list of extensions[] as defined in 'conf.py'.
# ; Mention the extensions you need. Some are loaded automatically
# ; and don't need to be mentioned.
#
# .................................................................................
# This is required for embedding YouTube videos
any_name_youtube = sphinxcontrib.youtube
[extlinks]
# .................................................................................
# ... (optional) If you want to be able to refer to issues like this:
# ... :issue:`number`
# .................................................................................
issue = https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument/issues/%s | Issue #
Includes.rst.txt¶
– optional (recommended for official documentation)
Documentation/Includes.rst.txt
This file can be the same for all Documentation projects!
Example:
.. This is 'Includes.rst.txt'. It is included at the very top of each and
every ReST source file in THIS documentation project (= manual).
.. This files lives at
https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument/blob/master/Documentation/Includes.rst.txt
.. More information about this file:
https://docs.typo3.org/typo3cms/HowToDocument/GeneralConventions/DirectoryFilenames.html#includes-txt
.. Define some additional text roles
See: https://docs.typo3.org/typo3cms/HowToDocument/WritingReST/InlineCode.html
.. ----------
.. text roles
.. ----------
.. role:: aspect(emphasis)
.. role:: html(code)
.. role:: js(code)
.. role:: php(code)
.. role:: pn(emphasis)
.. role:: rst(code)
.. role:: sep(strong)
.. role:: typoscript(code)
.. role:: ts(typoscript)
:class: typoscript
.. role:: yaml(code)
.. default-role:: code
.. ---------
.. highlight
.. ---------
.. By default, code blocks are php
.. highlight:: php
.editorconfig¶
– optional (strongly recommended)
.editorconfig
For more information, see .editorconfig.
Example:
.gitignore¶
– optional (strongly recommended)
.gitignore
All files listed in .gitignore will be ignored by Git. This is useful for generated files, that should not be added to your repository or for temporary files (e.g. backup files of your editor).
You can ignore additional files by adding them to your .git/info/exclude file.
The file .gitignore
will apply to anyone using the repository, .git/info/exclude
is for yourself
only and will not be included in the repository on GitHub when you push.
Use the file in this manual: .gitignore as a template.
Minimal example¶
# Git global ignore file
# for local exclude patterns please edit .git/info/exclude
# Example file see https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument/blob/master/.gitignore
# ignore generated documentation
*GENERATED*
About file (e.g. README.rst)¶
optional (recommended for official TYPO3 documentation)
This file will be displayed on the Git hoster (e.g. GitHub or Gitlab) when someone browses through the repositories. Use README.rst from this project as an example! (see source).

The link “Read online” will help people to jump directly to the rendered version.
Goal:
- Provide only basic information and point people to rendered docs
- Look good on Git hosters such as GitHub
Because of the order of the supported file formats (see Start file),
if a file such as Documentation/Index.rst
exists as well as README.rst
and has a higher priority, the README.rst is not rendered on docs.typo3.org.
The other file with higher priority is rendered on docs.typo3.org but README.rst is rendered on GitHub,
because that is one of the default filenames that GitHub uses to determine what to render.
In the official TYPO3 documentation, we follow this principle:
- README.rst usually contains 2 links:
- to the rendered documentation
- to the GitHub repository
Tip
Because of the flexibility of the supported file names,
a README.rst may actually be the documentation start page. This is the case, if no other supported
file with higher priority (such as Documentation/Index.rst
) exists. Do not do this for official documentation,
stick to the conventions. You are however free to do this for your extension documentation.
CONTRIBUTING.rst¶
– optional (recommended for official TYPO3 documentation)
This file serves the purpose of guiding people who come via GitHub towards our documentation for contributors. As a minimal solution, put a link in there to How to contribute to official documentation.
You can name it CONTRIBUTING.md
or CONTRIBUTING.rst
, but as we commonly use reST
here, it is best to stick to CONTRIBUTING.rst
.
Again, use CONTRIBUTING.rst from this manual as an example.
A link to the file will automatically be displayed by GitHub when someone enters the “Issues” area (and has not created an issue yet) or when someone creates an issue.