main
en
TYPO3 contributors
This document is published under the Creative Commons BY 4.0 license.
Tue, 04 Nov 2025 16:01:51 +0000
This guide contains information about contributing to TYPO3 documentation, writing documentation for TYPO3 extensions and formatting with reStructuredText (reST).
TYPO3 documentation is written in reStructuredText (reST) and rendered to HTML using a shared toolchain. Most documentation is hosted on https://docs.typo3.org and follows a common structure and style.
Table of content
Documentation may include:
Rendering converts .rst source files into styled HTML output. You can preview
docs locally using the official Docker container:
docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --config=DocumentationOpen the file saved to Documentation- in a
browser of your choice.
Everyone is welcome to contribute to TYPO3’s official documentation.
Most manuals are hosted on GitHub. You can suggest changes directly by clicking Edit on GitHub on any page.
For larger contributions or local editing, see the full guide at Contribute to the TYPO3 documentation.
To document your TYPO3 extension, create a Documentation folder in your
extension and add .rst files following the standard structure.
We provide a Docker command to get started with documenting an extension:
docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest initSee also How to document an extension.
Need help with TYPO3 documentation? Join the TYPO3 Slack workspace and post your question in the #typo3-documentation channel.
To register, visit: https://my.typo3.org/index.php?id=35
For general TYPO3 support, see https://typo3.org/help/.
You can also contact the Documentation Team by email: documentation@typo3.org
Cheat Sheet
Each reST document must have a title. It is overlined and underlined like this:
.. _rest-cheat-sheet:
=============================
Cheat sheet: reStructuredText
=============================
Some text.
.. _h2-headline:
H2 Headline
===========
Lorem Ipsum
.. _h3-headline:
H3 Headline
-----------
Some more text
There are more levels of headlines
References to documentation from the TYPO3 world should be copied from the wizard:
Hover over a headline to see if it is linkable, then click the link icon
They then look like this:
`ReST Cheat sheet <https://docs.typo3.org/permalink/h2document:rest-cheat-sheet>`_Permalinks are automatically checked and resolved during rendering.
External links can be copied into the document they will be auto detected. Or the standard reST Syntax can be used:
See also https://www.typo3.org or `the TER <https://extensions.typo3.org>`_.There are special links for composer packages and PHP classes (linking to the API):
Install :composer:`typo3/cms-seo` to listen to event
:php:`\TYPO3\CMS\Seo\Event\ModifyUrlForCanonicalTagEvent`.There is a dedicated chapter on links and references in reST: Links in ReStructured Text.
Short code blocks can be inserted directly into a reST file:
.. code-block:: php
:caption: EXT:my_extension/ext_localconf.php
defined('TYPO3') or die();Longer code blocks should be put into a file starting with an underscore and included:
.. literalinclude:: /snippets/_HelloWorld.php
:caption: EXT:my_extension/Classes/WorldDominance/HelloWorld.phpAll options of code blocks can also be applied to literal includes.
Configuration values can be defined like this:
.. confval:: label
:name: some-unique-label
:required: true
:type: string or LLL reference
:default: "abc"
The name of the field as shown in the form.Configuration values can have custom properties and displayed in special confval menues: Configuration values (confval).
* unordered
* Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam
nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat,
sed diam voluptua.
* list
#. ordered
#. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam
nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat,
sed diam voluptua.
#. listMore about Lists.
*italic text*, **bold text**, `general code` :typoscript:`page = PAGE`
:php:`\TYPO3\CMS\Seo\Event\ModifyUrlForCanonicalTagEvent` :guilabel:`Web > Page`
:composer:`typo3/cms-seo`Looks like this:
italic text, bold text, general code
page = PAGE
\TYPO3\ Web > Page
typo3/cms-seo
Comments can be written like this:
.. this is a comment
.. with another lineOr like this:
.. this is a comment
with another lineIf you want to use a character, which would create some special reST markup, with its normal meaning, you must escape it with a prepended "".
For example surrounding text with "" signs normally makes it show up in italics. By escaping the special characters "" you make the stars normal text characters:
\*non-italic\*See commonly used Commonmark Markdown Syntax in the TYPO3 Documentation Theme:
Cheat Sheet
Each document must have a title of level 1. You can use headers of additional levels, only use level 1 once per Markdown document
# Document header
Some text.
## H2 Headline
Lorem Ipsum
### H3 Headline
Lorem IpsumReferences to documentation from the TYPO3 world should be copied from the wizard:
Hover over a headline to see if it is linkable, then click the link icon
They then look like this:
[Configuration of the rendering - guides.xml](https://docs.typo3.org/permalink/h2document:guides-xml)External links can be copied into the document they will be auto detected. Or the standard md Syntax can be used:
See also https://www.typo3.org or (the TER)[https://extensions.typo3.org].Use the standard Markdown syntax for code blocks:
```php
<?php
defined('TYPO3') or die();
```
Lorem Ipsum Dolor: `$dolor`...
``Use `code` in your Markdown file.``- unordered
- Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam
nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat,
sed diam voluptua.
- list
1. ordered
2. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam
nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat,
sed diam voluptua.
10. list*italic text*, **bold text**, `$code = 'My Code'`Comments can be written like this:
<!-- this is a comment -->We support the rendering of the following GitHub Markdown style admonitions (Warning, Tip, etc):
> [!NOTE]
> Useful information that users should know, even when skimming content.
> [!TIP]
> Helpful advice for doing things better or more easily.
> [!IMPORTANT]
> Key information users need to know to achieve their goal.
> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.
> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.This chapter is an introduction and reference for writing documentation using reStructuredText (also referred to as reST).
It is recommended to read (or at least browse through) the ReST Cheat sheet: Using reStructuredText in TYPO3 Documentation and the general Coding guidelines for reST files first.
Or, use the ReST Cheat sheet: Using reStructuredText in TYPO3 Documentation, which contains the most commonly used markup on one page.
We cannot cover every reST markup that is available. For more information, see other resources, such as:
Table of contents
A code block consists of a code- directive and the actual code indented
by four spaces for consistency with other code bases.
A code block can have one or more options. To make orientation in code examples easier
try to always add a :caption: with the path and name of the file where the example should go:
.. code-block:: php
:caption: EXT:site_package/Configuration/TCA/Overrides/sys_template.php
/**
* Add default TypoScript (constants and setup)
*/
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addStaticFile(
'site_package',
'Configuration/TypoScript',
'Site Package'
);/**
* Add default TypoScript (constants and setup)
*/
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addStaticFile(
'site_package',
'Configuration/TypoScript',
'Site Package'
);Always use syntactically correct code in a code block.
Use placeholders in angle brackets
(<placeholder-) to refer to a place in the code where the exact
value is not important.
A code block has the following syntax:
.. code-block:: <language>
:caption: <caption>
<options>
<code>There must be a newline between the options and the code. There must not be a newline between the directive line and options or within options. Otherwise the rendering will fail.
The language of the code-block. We commonly use the following:
php,
typoscript (also for TSconfig),
yaml,
javascript,
html (also for Fluid),
shell,
xml,
plaintext.
See all available languages
The following options may be used, all options are optional,
but
caption is highly recommended:
.. code-block:: <language>
:caption: <caption>
:linenos:
:lineno-start: <start-number>
:emphasize-lines: <emphasized-line-numbers>
:name: <reference-label>
linenos
lineno-start
emphasize-lines
nameSee also the official sphinx documentation on code-blocks.
.. code-block:: php
:caption: EXT:site_package/Configuration/TCA/Overrides/sys_template.php
/**
* Add default TypoScript (constants and setup)
*/
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addStaticFile(
'site_package',
'Configuration/TypoScript',
'Site Package'
);/**
* Add default TypoScript (constants and setup)
*/
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addStaticFile(
'site_package',
'Configuration/TypoScript',
'Site Package'
);.. code-block:: php
:caption: EXT:site_package/Configuration/TCA/Overrides/sys_template.php
:linenos:
:emphasize-lines: 4, 7
/**
* Add default TypoScript (constants and setup)
*/
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addStaticFile(
'site_package',
'Configuration/TypoScript',
'Site Package'
);/**
* Add default TypoScript (constants and setup)
*/
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addStaticFile(
'site_package',
'Configuration/TypoScript',
'Site Package'
);To emphasize changes that should be made:
.. code-block:: diff
:caption: ext_localconf.php.diff
<?php
-defined('TYPO3_MODE') or die();
+defined('TYPO3') or die(); <?php
-defined('TYPO3_MODE') or die();
+defined('TYPO3') or die();Hint
You can use diff tools such as the
bartlweb diff file generator. Make
sure to use the type unified context
To display an expandable directory tree, use the directive '.. directory-tree::'.
.. code-block:: none
:caption: Page tree of directory :file:`vendor/composer`
$ tree vendor/composer
├── ClassLoader.php
├── LICENSE
├── autoload_classmap.php
├── ...
└── installed.jsonvendor/composer
$ tree vendor/composer
├── ClassLoader.php
├── LICENSE
├── autoload_classmap.php
├── ...
└── installed.jsonAttention
Please: No syntax errors!
Syntax highlighting only works if the lexer can parse the code without errors. In other words: If there's a syntax error in the code the highlighting will not work.
.. code-block:: php
$a = array(
'one' => 1,
// ...
);.. code-block:: php
$a = array(
'one' => 1,
...
);The following languages are supported. They can be used in a
code-
and a
literalinclude directive.
A drawback of code blocks is that most editors cannot properly highlight or
indent code within code blocks. The directive
literalinclude enables you
to store longer code blocks in an external file with the proper file extension.
The
literalinclude directive imports the file and displays its content as
code block.
.. literalinclude:: /_CodeSnippets/LiteralIncludes/example.yaml
:language: yaml
:emphasize-lines: 5,10-13
:linenos:See also literalinclude directive.
Placeholders in this context are named tags in code and
example URLs where the exact value does not matter,
but is referenced in the surrounding documentation.
Use the Backus-Naur form <placeholder- for placeholders in code and
URLs, i.e. use angle brackets to encapsulate the placeholder name.
For example in PHP
Set up a controller class to handle user interaction with the entity data
model:
.. code-block:: php
class <Entity>Controller extends ActionController
{
..
}
where `<Entity>` corresponds to the entity data model class name.or on the command line
Importing a TYPO3 dump file is as simple as running:
.. code-block:: bash
typo3/sysext/core/bin/typo3 impexp:import <file>
where `<file>` can be the absolute path on the server or the relative path
in the TYPO3 project folder.or in an example URL
The TYPO3 backend normally appends the session token ID to the URL as
follows: :samp:`https://example.org/typo3/main?token=<token-id>`.In the XML and HTML markup languages, which make extensive use of angle
brackets, the comment tag
<!-- placeholder- is used to insert
placeholders. A <placeholder- looks like a regular element and would lead to confusion.
For historic reasons the
:caption: option is missing in many code blocks.
Try to add them whenever you touch the RST files. Do not add new code blocks
without a caption stating the file name. It is often very confusing for new
developers where a certain code snippet should go. The recommended file name
can help to clear this up.
We recommend that you always write the language name after the code block directive. This makes it easier for first time contributors to adjust or copy-paste code blocks. For historic reasons there are code blocks without an explicit language.
If you do not explicitly set the language, the default language (PHP) is used.
In the past a simplified shorthand directive was widely used: A sentence ending
with two double colon
::, followed by a new line and an indented
block of code. This quick syntax has several drawbacks:
You can change these code blocks like this:
The extension already contains some unit tests that extend `typo3/testing-framework`'s base
-unit test class in directory :file:`Tests/Unit/Hooks` (stripped):
.. code-block:: php
:caption: <extension_key>/Tests/Unit/Hooks/DataHandlerFlushByTagHookTest.php
<?php
namespace Lolli\Enetcache\Tests\Unit\Hooks;The
confval directive can be used to document configuration values
in a structured way, independent of the programming language.
In a TYPO3 context, it can be used to document configuration values
stored in PHP arrays (TCA, global configuration variables),
TypoScript (TypoScript setup, TSconfig), XML (FlexForms, XLIFF) and
YAML (SiteConfiguration, EXT:form).
Using the
confval directive has several benefits:
Each configuration value name may only be used once. In large references with different contexts you can define individual configuration schemas for each context.
Table of contents
true
The name of the field as shown in the form.
.. confval:: label
:name: some-unique-label
:required: true
:type: string or LLL reference
The name of the field as shown in the form.
$GLOBALS['TYPO3_CONF_VARS']['SYS']['fileCreateMask']
File mode mask for Unix file systems (when files are uploaded/created).
.. confval:: fileCreateMask
:name: some-unique-fileCreateMask
:type: text
:default: 0664
:Path: :php:`$GLOBALS['TYPO3_CONF_VARS']['SYS']['fileCreateMask']`
File mode mask for Unix file systems (when files are uploaded/created).Each confval must have at least a title. If that title is not unique within
the manual the confval must also have the :name: attribute, followed by a
unique name. Names are case-insensitive and convert all special signs into a dash.
.. confval:: [title]
:name: [unique-name]There are several reserved attributes:
:type::default::required::name::class:noindexAll other attributes are output the way they are written:
$GLOBALS['TYPO3_CONF_VARS']['SYS']['someSetting']
Lorem Ipsum Dolor sit
.. confval:: fileCreateMask
:name: some-unique-someSetting
:type: string
:default: 0664
:Path: :php:`$GLOBALS['TYPO3_CONF_VARS']['SYS']['fileCreateMask']`
Lorem Ipsum Dolor sitHint
Too much inline code can make the information on a page unreadable. If this is the case, consider using Code blocks with syntax highlighting.
Any text inside single or double backticks is printed as inline code. Double backticks allow unescaped backticks to be used in the code:
By convention single backticks are used unless double are needed.
You can also use text roles with one of the predefined languages to display more information to the user. For the most common languages, automatic detection provides more context for the user.
$variable = 'Some general PHP'
\TYPO3\CMS\Core\Core\Environment TYPO3 class with fully qualified name
Environment TYPO3 class with short name
\Symfony\Component\Dotenv\Dotenv External class
$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport'] configuration values
page = PAGE
TCAdefaults.pages.hidden
<f:debug>{myVariable}</f:debug>
<code>
code#mycode {font-family: courier}
alert('test')
./vendor/bin/typo3 help * :php:`$variable = 'Some general PHP'`
* :php:`\TYPO3\CMS\Core\Core\Environment` TYPO3 class with fully qualified name
* :php-short:`\TYPO3\CMS\Core\Core\Environment` TYPO3 class with short name
* :php:`\Symfony\Component\Dotenv\Dotenv` External class
* :php:`$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport']` configuration values
* :typoscript:`page = PAGE`
* :tsconfig:`TCAdefaults.pages.hidden`
* :fluid:`<f:debug>{myVariable}</f:debug>`
* :html:`<code>`
* :css:`code#mycode {font-family: courier}`
* :js:`alert('test')`
* :bash:`./vendor/bin/typo3 help`
PHP classes from the TYPO3 Core are automatically linked to https://api.typo3.org and display the PHP doc comment (if any) in the overlay.
All named inline code roles show an overlay where the code can be conveniently copied and information on the language of the code.
In order to describe PHP code in TYPO3's documentation, our toolchain has an integrated extension inspired by the PHP domain of the Sphinx project.
The source code of the PHP domain extension is located on GitHub:
https://github.com/TYPO3-Documentation/guides-php-domain
Datetime class
Set the date.
The year.
The month.
The day.
Either false on failure, or the datetime object for method chaining.
.. php:namespace:: Vendor\Extension
.. php:class:: DateTime
Datetime class
.. php:method:: setDate($year, $month, $day)
Set the date.
:param int $year: The year.
:param int $month: The month.
:param int $day: The day.
:returns: Either false on failure, or the datetime object for method chaining.
.. php:method:: setTime($hour, $minute[, $second])
Set the time.
:param int $hour: The hour
:param int $minute: The minute
:param int $second: The second
:returns: Either false on failure, or the datetime object for method chaining.
.. php:const:: ATOM
Y-m-d\TH:i:sPUse namespaces wherever they are applicable.
Create a namespace once per document that becomes the link target:
.. php:namespace:: Vendor\ExtensionPSR-14 events are - technically - PHP classes. So they can be documented just like PHP classes.
PSR-14 to alter (or empty) a canonical URL for the href="" attribute of a canonical URL.
.. php:namespace:: TYPO3\CMS\Seo\Event
.. php:class:: ModifyUrlForCanonicalTagEvent
PSR-14 to alter (or empty) a canonical URL for the href="" attribute of a canonical URL.
.. php:method:: getUrl()
:returntype: string
.. php:method:: setUrl(string url)
:param string $url: the urlDefines which error levels should result in an exception thrown.
The integer representing the E_* error level to handle as exceptions
Handles an error. If the error is registered as exceptionalError it will be converted into an exception, to be handled by the configured exceptionhandler.
Additionally the error message is written to the configured logs. If application is backend, the error message is also added to the flashMessageQueue, in frontend the error message is displayed in the admin panel (as TsLog message).
The error level - one of the E_* constants
The error message
Name of the file the error occurred in
Line number where the error occurred
bool
\TYPO3\
.. php:namespace:: TYPO3\CMS\Core\Error
.. php:interface:: ErrorHandlerInterface
.. php:method:: setExceptionalErrors($exceptionalErrors)
Defines which error levels should result in an exception thrown.
:param int $exceptionalErrors: The integer representing the E_* error level to handle as exceptions
.. php:method:: handleError($errorLevel, $errorMessage, $errorFile, $errorLine)
Handles an error.
If the error is registered as exceptionalError it will be converted into
an exception, to be handled by the configured exceptionhandler.
Additionally the error message is written to the configured logs.
If application is backend, the error message is also added to the
flashMessageQueue, in frontend the error message is displayed in the
admin panel (as TsLog message).
:param int $errorLevel: The error level - one of the E_* constants
:param string $errorMessage: The error message
:param string $errorFile: Name of the file the error occurred in
:param int $errorLine: Line number where the error occurred
:returntype: bool
:throws: :php:class:`TYPO3\\CMS\\Core\\Error\\Exception`
.. php:const:: ERROR_HANDLED
true
.. php:attr:: testattr
Value of some attribute.Exception for root line traversal when a page within the root line traversal is missing / can not be resolved.
.. php:namespace:: TYPO3\CMS\Core\Exception\Page
.. php:exception:: BrokenRootLineException
Exception for root line traversal when a page within the root line traversal
is missing / can not be resolved... php:namespace:: TYPO3\CMS\Core\Context
.. php:trait:: ContextAwareTrait
.. php:attr:: $context
.. php:method:: setContext(Context $context)
:param TYPO3\\CMS\\Core\\Context\\Context $context: The context
.. php:method:: getContext()
:returntype: TYPO3\\CMS\\Core\\Context\\ContextNote
Backslashes have to be escaped by
\\.
TYPO3\CMS\Core\Exception\Page * :php:exc:`TYPO3\\CMS\\Core\\Exception\\Page\\BrokenRootLineException`
* :php:ns:`TYPO3\\CMS\\Core\\Exception\\Page`
* :php:class:`Vendor\\Extension\\DateTime`
* :php:class:`TYPO3\\CMS\\Seo\\Event\\ModifyUrlForCanonicalTagEvent`
* :php:interface:`TYPO3\\CMS\\Core\\Error\\ErrorHandlerInterface`
* :php:func:`Vendor\\Extension\\DateTime::setTime()`
* :php:const:`Vendor\\Extension\\DateTime\\ATOM`With the
:any: directive you can link to any PHP domain entity:
Vendor\Extension\DateTime Vendor\Extension\DateTime::setTime() * :any:`Vendor\\Extension\\DateTime`
* :any:`Vendor\\Extension\\DateTime::setTime()`We are currently working on the automatic generation of PHP domain syntax from PHP classes within the TYPO3 Screenshots tool.
When an extension features Settings definitions
for site settings these can be automatically documented by including the settings
definition file. The special syntax PROJECT: can be used to load the file
from the directory of the extension instead of the Documentation folder only.
.. typo3:site-set-settings:: PROJECT:/Configuration/Sets/MySet/settings.definitions.yaml
:name: my-set
:type:
:Label: max=30
:default: max=10
| Name | Type | Label | Default |
|---|---|---|---|
color
|
Background color | "... | |
string
|
Browser-native image lazy load... | "... | |
string
|
List of allowed HTML tags when... | "... |
color
"#129845"
This will validate the given color string
string
"lazy"
Can be "lazy" (browsers could choose to load images later), "eager" (load images right away) or "auto" (browser will determine whether the image should be lazy loaded or not)
string
"a, abbr, acronym, address, article, aside, b, bdo, big, blockquote, br, caption, center, cite, code, col, colgroup, dd, del, dfn, dl, div, dt, em, figure, font, footer, header, h1, h2, h3, h4, h5, h6, hr, i, img, ins, kbd, label, li, link, meta, nav, ol, p, pre, q, s, samp, sdfield, section, small, span, strike, strong, style, sub, sup, table, thead, tbody, tfoot, td, th, tr, title, tt, u, ul, var"
The custom parameters :type:, :Label: etc can be used to configure
which aspects of the settings should be shown in the overview table.
A :name: can be used to create a namespace when there are several sets. All
links to the configuration values will be prefixed then.
This is the first item's accordion body. It is shown by default, until the collapse plugin adds the appropriate classes that we use to style each element. These classes control the overall appearance, as well as the showing and hiding via CSS transitions.
You can modify any of this with custom CSS
or overriding our default variables. It's also worth noting that just about any HTML can go within
the .accordion-, though the transition does limit overflow.
Placeholder content for this accordion, which is intended to demonstrate the .accordion-flush class. This is the second item's accordion body. Let's imagine this being filled with some actual content.
Placeholder content for this accordion, which is intended to demonstrate the .accordion-flush class. This is the third item's accordion body. Nothing more exciting happening here in terms of content, but just filling up the space to make it look, at least at first glance, a bit more representative of how this would look in a real-world application.
.. accordion::
:name: accordionExample
.. accordion-item:: Accordion Item #1
:name: headingOne
:header-level: 2
:show:
**This is the first item's accordion body.** It is shown by default, [..]
.. accordion-item:: Accordion Item #2
:name: headingTwo
:header-level: 2
Placeholder content for this accordion [..]
.. accordion-item:: Accordion Item #3
:name: headingThree
:header-level: 2
Placeholder content for this accordion [..]Placeholder content for this accordion
Placeholder content for this accordion
Let's imagine this being filled with some actual content.
.. accordion::
:name: accordionExample2
.. accordion-item:: Accordion Item #1
:name: headingOne2
:header-level: 3
Placeholder content for this accordion
.. accordion-item:: Accordion Item #2
:name: headingTwo2
:header-level: 3
Placeholder content for this accordion
.. accordion-item:: Accordion Item #3
:name: headingThree2
:header-level: 3
Let's imagine this being filled with some actual content.Apples are green, or sometimes red.
Pears are green.
Oranges are orange.
var makeNoise = function() {
console.log("Pling!");
};
makeNoise();
// → Pling!
var power = function(base, exponent) {
var result = 1;
for (var count = 0; count < exponent; count++)
result *= base;
return result;
};
console.log(power(2, 10));
// → 1024
.. accordion::
:name: accordionExample3
.. accordion-item:: Accordion Item #1
:name: headingOne3
:header-level: 3
.. tabs::
.. tab:: Apples
Apples are green, or sometimes red.
.. tab:: Pears
Pears are green.
.. tab:: Oranges
Oranges are orange.
.. accordion-item:: Accordion Item #2
:name: headingTwo3
:header-level: 3
:show:
.. code-block:: javascript
[...]
.. accordion-item:: Accordion Item #3
:name: headingThree3
:header-level: 3
.. image:: /_Images/q150_ffffff.png
:alt: Image with background color #ffffff
:class: with-border with-shadowThe following directives are called Admonitions. You can use them to point out additional or important information.
.. seealso::
`Admonitions <http://docutils.sourceforge.net/0.7/docs/ref/rst/directives.html#admonitions>`__See also
.. note::
A noteNote
A note
.. tip::
A tipTip
A tip
You may also use the admonition hint, but this is very similar and tip is more commonly used in the documentation.
.. warning::
Some text pointing out something that people should be warned about.Warning
Some text pointing out something that people should be warned about.
You may also use the admonitions caution or even danger if the severity of the warning must be stressed.
.. attention::
An attentionAttention
An attention
The admonitions listed here are the most commonly used in the TYPO3 documentation.
For more see reStructuredText directives in docutils documentation.
Cards are used to group content together and provide a brief introduction on a given subject.
Deprecated since version 0.2.40
Cards were previously created by using nested
.. container::
directives with manually applied classes. The largest disadvantages were
a large number of nested blocks and having to apply many classes.
We discourage using containers for cards and suggest to switch to the cards directive.
Written for new users, this chapter introduces some of TYPO3s core concepts including the backend, TYPO3s administration interface.
System requirements for the host operation system, including its web server and database and how they should be configured prior to installation.
.. card-grid::
:columns: 1
:columns-md: 2
:gap: 4
:class: pb-4
:card-height: 100
.. card:: :ref:`Concepts <t3start:Concepts>`
Written for new users, this chapter introduces some of TYPO3s
core concepts including the backend, TYPO3s administration
interface.
.. card:: :ref:`System Requirements <t3start:System-Requirements>`
System requirements for the host operation system, including
it's web server and database and how they should be configured
prior to installation.
Cards can be used to shortly introduce topics and generate overview pages.
Tabs can be used to present a topic from different perspectives.
Cards can be used to shortly introduce topics and generate overview pages.
This card has the image at the bottom
.. card-grid::
:columns: 1
:columns-md: 2
:gap: 4
:class: pb-4
:card-height: 100
.. card:: :ref:`Cards <rest-cards>`
.. card-image:: /_Images/cards.png
:alt: Cards, example output
Cards can be used to shortly introduce topics and generate
overview pages.
.. card:: :ref:`Tabs <rest-tabs>`
.. card-image:: /_Images/tabs.png
:alt: Tabs, example output
Tabs can be used to present a topic from different perspectives.
.. card:: :ref:`Cards <rest-cards>`
.. card-image:: /_Images/cards.png
:alt: Cards, example output
Cards can be used to shortly introduce topics and generate
overview pages.
.. card:: :ref:`Tabs <rest-tabs>`
.. card-image:: /_Images/tabs.png
:alt: Tabs, example output
:position: bottom
This card has the image at the bottomParts of the text in reST source can be "commented out":
Any text which begins with an explicit markup start but doesn't use the syntax of any of the constructs above, is a comment.
See http://docutils.sourceforge.net/docs/user/rst/quickref.html#comments
This means: write ..␠, that is dot-dot-blank at the beginning of the
line, taking the indentation level into account.
Example:
.. So here we have a comment.
It can spread over lines as
long as you keep the indentation.
Example:
.. This text will not be shown,
but, for instance, in HTML might be
rendered as an HTML comment, if the html writer is set up for that.
Example:
.. here we start an unordered list:
* one
* two
.. this is another comment. Since it's within the list it is aligned
with 'two', which is the contents of the second list item
* threeQ: What characters can I use?
A: You may enter any Unicode character directly. There is no other way to specify characters. The default encoding of a file is utf-8.
Keep in mind that while you CAN use any Unicode character not all of them will be displayed. In general fonts contain glyphs for common characters only.
| search
| ⃪ ⃮ ⃯ ← ↑ → ↓ ↔ ↕ ↖ ↗ ↘ ↙
↚ ↛ ↜ ↝ ↞ ↟ ↠ ↡ ↢ ↣ ↤ ↥ ↦ ↧ ↨
↩ ↪ ↫ ↬ ↭ ↮ ↯ ↰ ↱ ↲ ↳ ↴ ↵ ↶ ↷
↸ ↹ ↺ ↻ ⇄ ⇅ ⇆
⇍ ⇎ ⇏ ⇐ ⇑ ⇒ ⇓ ⇔ ⇕ ⇖ ⇗ ⇘ ⇙ ⇚ ⇛
⇜ ⇝ ⇞ ⇟ ⇠ ⇡ ⇢ ⇣ ⇤ ⇥
⇦ ⇧ ⇨ ⇩ ⇪ ⇫ ⇬ ⇭ ⇮ ⇯ ⇰
⇱ ⇲ ⇳ ⇴ ⇵ ⇷ ⇸ ⇹ ⇺ ⇻ ⇼ ⇽ ⇾ ⇿ ⌁
⍇ ⍈ ⍐ ⍗ ⍼ ⎋
➔ ➘ ➙ ➚ ➛ ➜ ➝ ➞ ➟ ➠ ➡ ➥ ➦ ➧ ➨
➩ ➪ ➫ ➬ ➭ ➮ ➯ ➱ ➲
➳ ➴ ➵ ➶ ➷ ➸ ➹ ➺ ➻ ➼ ➽ ➾
⟰ ⟱ ⟲ ⟳ ⟴
⟵ ⟶ ⟷ ⟸ ⟹ ⟺ ⟻ ⟼ ⟽ ⟾
⟿ ⤀ ⤁ ⤂ ⤃ ⤄ ⤅ ⤆ ⤇ ⤈ ⤉ ⤊ ⤋
⤌ ⤍ ⤎ ⤏ ⤐ ⤑ ⤒ ⤓ ⤔ ⤕ ⤖ ⤗ ⤘ ⤙ ⤚ ⤛ ⤜ ⤝ ⤞ ⤟ ⤠
⤡ ⤢ ⤣ ⤤ ⤥ ⤦ ⤧ ⤨ ⤩ ⤪ ⤭ ⤮ ⤯ ⤰ ⤱ ⤲
⤳ ⤴ ⤵ ⤶ ⤷ ⤸ ⤹ ⤺ ⤻ ⤼ ⤽ ⤾ ⤿
⥀ ⥁ ⥂ ⥃ ⥄ ⥅ ⥆ ⥇ ⥈ ⥉ ⥰ ⥱ ⥲ ⥳ ⥴ ⥵
⥶ ⥷ ⥸ ⥹ ⥺ ⥻ ⦨ ⦩ ⦪ ⦫ ⦬ ⦭ ⦮ ⦯ ⦳ ⦴ ⦽ ⧪ ⧬ ⧭ ⨗
⬀ ⬁ ⬂ ⬃ ⬄
⬅ ⬆ ⬇ ⬈ ⬉ ⬊ ⬋ ⬌ ⬍
⬎ ⬏ ⬐ ⬑ ⬰ ⬲ ⬳ ⬴ ⬵ ⬶ ⬷ ⬸
⬹ ⬺ ⬻ ⬼ ⬽ ⬾ ⬿ ⭀ ⭁ ⭂ ⭃ ⭄
⭅ ⭆ ⭇ ⭈ ⭉ ⭊ ⭋ ⭌ ⽮ ꜛ ꜜ ￩ ￪ ￫ ￬
|| search
| • ‣ ⁃ ⁌ ⁍ ∙ ◘ ◦ ☙ ❥ ❧ ⦾ ⦿ 🚅
|| search
| ☑ ✅ ✓ ✔
|| search
| ⓪ ① ② ③ ④ ⑤ ⑥ ⑦ ⑧ ⑨
|| search
| ⒶⒷⒸⒹⒺⒻⒼⒽⒾⒿⓀⓁⓂⓃⓄⓅⓆⓇⓈⓉⓊⓋⓌⓍⓎⓏ
| ⓐⓑⓒⓓⓔⓕⓖⓗⓘⓙⓚⓛⓜⓝⓞⓟⓠⓡⓢⓣⓤⓥⓦⓧⓨⓩ
|| search
| ⑩⑪⑫⑬⑭⑮⑯⑰⑱⑲ ⑳㉑㉒㉓㉔㉕㉖㉗㉘㉙ ㉚㉛㉜㉝㉞㉟㊱㊲㊳㊴ ㊵㊶㊷㊸㊹㊺㊻㊼㊽㊾ ㊿
|| search
| ⓵ ⓶ ⓷ ⓸ ⓹ ⓺ ⓻ ⓼ ⓽
|| search
| ⓿ ❶ ❷ ❸ ❹ ❺ ❻ ❼ ❽ ❾
|| search
| ❿⓫⓬⓭⓮⓯⓰⓱⓲⓳ ⓴
|| search
| "«»―‘’‚‛“”„‟‹›❛❜❝❞❟❠❮❯〝〞〟＂
| " « » ― ‘ ’ ‚ ‛ “ ” „ ‟ ‹ › ❛ ❜ ❝ ❞ ❟ ❠ ❮ ❯ 〝 〞 〟 ＂
|| search
| ⒜⒝⒞⒟⒠⒡⒢⒣⒤⒥⒦⒧⒨⒩⒪⒫⒬⒭⒮⒯⒰⒱⒲⒳⒴⒵
|| search
| ≛ ⋆ ⍟ ⍣ ★ ☆ ☪ ⚝ ✡ ✦ ✧ ✩ ✪ ✫ ✬ ✭ ✮ ✯ ✰ ✴ ✵ ✶ ✷ ✸ ✹ ❂ ⭐ ⭑ ⭒ 🌟 🌠 🔯 ٭
|* ``:literal:`␠abc``` → :literal:`␠abc`
* ```␠abc``` → `␠abc`
* \`\`␠abc\`\` → ``␠abc``:literal:`␠abc` → ␠abc`␠abc` → ␠abc␠abcThere are several ways to create tables in reST.
It is recommended that you do not use large tables as they are not responsive.
+----------+----------+
| Header 1 | Header 2 |
+==========+==========+
| 1 | one |
+----------+----------+
| 2 | two |
+----------+----------+| Header 1 | Header 2 |
|---|---|
| 1 | one |
| 2 | two |
http://docutils.sourceforge.net/docs/user/rst/quickref.html#tables
You can use this table generator to create a grid table.
======== ========
Header 1 Header 2
======== ========
1 one
2 two
======== ========| Header 1 | Header 2 |
|---|---|
| 1 | one |
| 2 | two |
http://docutils.sourceforge.net/docs/user/rst/quickref.html#tables
.. csv-table:: Numbers
:header: "Header 1", "Header 2"
:widths: 15, 15
1, "one"
2, "two"| Header 1 | Header 2 |
|---|---|
| 1 | one |
| 2 | two |
https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table-1
t3- is a custom directive, created by the t3SphinxThemeRtd
template. If you want your .rst file to be correctly rendered on other
platforms as well (for example GitHub), you should not use this.
.. t3-field-list-table::
:header-rows: 1
- :Header1: Header1
:Header2: Header2
- :Header1: 1
:Header2: one
- :Header1: 2
:Header2: two|
Header1 |
Header2 |
|---|---|
|
1 |
one |
|
2 |
two |
They provide a compact way to present a topic from different perspectives, with each perspective presented in a tab. When the reader changes tabs, this change is synchronized in all tab content elements.
For example, if the reader is guided through the TYPO3 installation with text and five code blocks, they could switch from Bash to Powershell instructions in the first code block, and all subsequent code blocks would also automatically switch to Powershell.
composer create-project typo3/cms-base-distribution:^11 example-project-directorycomposer create-project "typo3/cms-base-distribution:^11" example-project-directorytouch example-project-directory/public/FIRST_INSTALLecho $null >> public/FIRST_INSTALL.. tabs::
.. group-tab:: bash
.. code-block:: bash
composer create-project typo3/cms-base-distribution:^11 example-project-directory
.. group-tab:: powershell
.. code-block:: powershell
composer create-project "typo3/cms-base-distribution:^11" example-project-directory
.. tabs::
.. group-tab:: bash
.. code-block:: bash
touch example-project-directory/public/FIRST_INSTALL
.. group-tab:: powershell
.. code-block:: powershell
echo $null >> public/FIRST_INSTALLAs an example, tabs are used in the Getting Started Guide in the chapter Installation.
We have 3 directives to mark versions in the manuals.
The incentive is that information which is important for migration can be marked and semi-automatically be removed after one or two versions.
.. versionadded:: 10.2
Starting with TYPO3 10.2 hooks and signals have been replaced by a PSR-14 based
event dispatching system.New in version 10.2
Starting with TYPO3 10.2 hooks and signals have been replaced by a PSR-14 based event dispatching system.
For emphasis, the directive can also be placed into one of the admonitions:
.. tip::
.. versionadded:: 10.2
Starting with TYPO3 10.2 hooks and signals have been replaced by a PSR-14 based
event dispatching system.Tip
New in version 10.2
Starting with TYPO3 10.2 hooks and signals have been replaced by a PSR-14 based event dispatching system.
.. deprecated:: 10.2
The hook shown here is deprecated since TYPO3 10.2 - use a custom
PSR-15 middleware instead.Deprecated since version 10.2
The hook shown here is deprecated since TYPO3 10.2 - use a custom PSR-15 middleware instead.
.. versionchanged:: 10.4.34
The bug ... was fixed with version 10.4.23 ...Changed in version 10.4.34
The bug ... was fixed with version 10.4.23 ...
The special .. typo3: directive can be used to display the
information about a Fluid ViewHelper, including all arguments.
The information on the available arguments is included from a .json file.
See also https://github.com/TYPO3-Documentation/fluid-documentation-generator
on how to generate the input file.
Warning
Usage of the viewhelper directive outside of the Fluid ViewHelper Reference is still considered experimental.
.. typo3:viewhelper:: link.external
:source: /resources/global_viewhelpers_demo.json
{
"namespace": "http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers",
"viewHelpers": {
"split": {
"className": "TYPO3Fluid\\Fluid\\ViewHelpers\\SplitViewHelper",
"...": "..."
},
"link.external":{
"className": "TYPO3\\CMS\\Fluid\\ViewHelpers\\Link\\ExternalViewHelper",
"namespace": "TYPO3\\CMS\\Fluid\\ViewHelpers",
"name": "Link\\ExternalViewHelper",
"tagName": "link.external",
"documentation": "A ViewHelper for creating links to external targets.\n\nExamples\n========\n...",
"xmlNamespace": "http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers",
"docTags": {},
"argumentDefinitions": {
"uri": {
"name": "uri",
"type": "string",
"description": "The URI that will be put in the href attribute of the rendered link tag",
"required": true,
"defaultValue": null,
"escape": null
}
},
"allowsArbitraryArguments": true
},
"...": "..."
}
}viewhelper directive | Name | Type |
|---|---|
| string | |
| string, local file path, relative or absolute | |
| string | |
| bool |
Name of the ViewHelper as used as key in the the JSON include file.
Path to the source JSON file to be included. Can be relative or absolute.
.. viewhelper:: my.viewhelper
:source: /some/absolute/path/_includes/_my_viewhelper.json
.. viewhelper:: my.viewhelper
:source: ../_includes/_my_viewhelper.jsonThe path is calculated starting from the Documentation directory.
It is not possible to include files from different locations in an extension.
name
Ordering of the argument list.
.. typo3:viewhelper:: split
:source: resources/global_viewhelpers_demo.json
:sortBy: name
.. typo3:viewhelper:: image
:source: resources/global_viewhelpers_demo.json
:sortBy: jsonIf set the ViewHelper will only be displayed but cannot be linked and is not
added to any indexes. This is useful if the same ViewHelper should be
displayed in several places within the same document. In such a case there
would be a clash of identifiers and warnings in the rendering if :noindex:
is not set.
Get the YouTube ID.
Example: The URL is https://.
The id is the text after v= and up to the next & or the end of the
URL.
Here: r.
Embed the Video using the ID
2018-01-19 by Mathias Schreiber
.. youtube:: wNxO-aXY5YwHow it looks:
2018-01-19 by Mathias Schreiber
You can upload images in any folder below Documentation and use it like that:
For details see Using images in ReST documentation.
You can also use Embedded PlantUML diagrams.
Attention
For official and Core manuals please follow the Guidelines for creating images.
You can use the The example screenshot project. It already follows most of the rules stated below. There has been no automatic screenshot tool since TYPO3 v11 as it proved to be to complicated to maintain.
Attention
For official and Core manuals please follow the Guidelines for creating images.
We recommend to use the .. figure:: directive. It works just like
.. image:: save that you can add a descriptive text as content.
Always use the parameter :alt: to add a descriptive text for visually impaired
and search engine / artificial intelligence bots scanning our docs.
Example:
Optional parameters for images and figures:
:target: link target:width: : width of image, use for example px (for example :width: 100px:scale: : scale images, for example :scale: 65Additional parameters can be found on the docutils page reStructuredText Directives
.. figure:: /_Images/a4.jpg
:alt: some image
:target: https://typo3.org
:class: with-shadow
:scale: 50This is the image caption
.. figure:: /_Images/a4.jpg
:alt: some image
:target: https://typo3.org
:width: 100px
This is the image captionIn order to render diagrams in the TYPO3 documentation, PlantUML is integrated into the rendering process.
Basic diagrams can be embedded directly into the reStructuredText markup:
.. uml::
:caption: Some Caption
class -> otherClass : messageThis will be rendered as:
.. uml:: _complex_uml.plantuml
:align: center
:caption: Figure 1-1: Application flow
:width: 1000This will be rendered as:
Put a file called _complex_ in the same directory as
the reST file:
enum FeedFormat {
ATOM
JSON
RSS
}
interface AuthorInterface
interface CategoryInterface
interface FeedInterface
interface FeedFormatAwareInterface
interface ImageInterface
interface ItemInterface
interface RequestAwareInterface
class Author
class Image
class Item
class YourFeed
note left: This is your feed implementation class
YourFeed -[hidden]> FeedFormat
Author <|.. AuthorInterface
Category <|.. CategoryInterface
Image <|.. ImageInterface
Item <|.. ItemInterface
FeedInterface ..|> YourFeed : required
FeedFormatAwareInterface ..|> YourFeed : optional
RequestAwareInterface ..|> YourFeed : optional
Item "1" *-- "0 .. n" Author : contains
YourFeed "1" *-- "0 .. n" Author : contains
YourFeed "1" *-- "0 .. n" Category : contains
YourFeed "1" *-- "0 .. 1" Image : contains
YourFeed "1" *-- "0 .. n" Item : contains
YourFeed .. FeedFormat : used in attributes
In general we support any inline markup in reStructuredText that was previously supported by Sphinx.
For example, use one asterix for italics *italic* and two for bold **bold**.
Links are described in depth in chapter Links in ReStructured Text and are also classed as inline text roles.
All named inline text roles
have the following syntax: :text-role-name:`Some Text`.
Some text roles expect the text inside backticks to have a particular syntax.
See also
Table of contents
This is normal text. **This is bold text**How it looks:
This is normal text. This is bold text
This is normal text. *This is italic text.*How it looks:
This is normal text. This is italic text.
Hint
Make sure there is no space between the markup and the styled text.
In general we support any text roles in reStructuredText that were previously supported by Sphinx.
The TYPO3 Documentation Rendering Container also supports the
Docutils Standard Text Roles
except for :raw:, as that could pose security issues.
See also
:php:, :typoscript:, etc.public/fileadmin config/system/settings.php * :abbr:`LIFO (last-in, first-out)`
* :path:`public/fileadmin`
* :file:`config/system/settings.php`
* :guilabel:`Web > Pages`
* Press :kbd:`ctrl` + :kbd:`s`
* :composer:`typo3/cms-core`, :composer:`georgringer/news`
* See also :issue:`102056` or :issue:`This issue <99508>` for forge issues
* :t3ext:`fal_securedownload` or :t3ext:`EXT:news`, :t3ext:`news <EXT:news>`
* :t3src:`backend/Configuration/Backend/Routes.php`In reStructuredText (reST) there are multiple methods to define links to different targets. The following chapter describe those most commonly used in TYPO3 documentation.
Link anchors assign a unique name to a headline and its section. These anchors can be used in internal references and references between TYPO3 manuals.
As long as the anchor of a section stays the same the section can be moved to another page or the headline can be renamed and references will still go to the correct target.
You can define a link anchor with a label for a section.
In the following example, the link target
inline- is assigned
to the section with the title "Inline columns".
Place the link anchor definition directly before the section header:
.. _inline-columns:
Inline columns
==============Link anchors should contain alphanumeric signs plus hyphen: ([a-).
All other signs are automatically transformed by the symfony
\Symfony\.
A recommended recipe could be:
--.. _ at the beginning.: at the end.We are currently trying to let Fractor support <https://
this and other transformations.
At https://api.typo3.org/ all classes and interfaces of the TYPO3 Core are listed with their public members and descriptions. The API itself also links to the source code on GitHub. You can use implicit and explicit links to these:
.. Explicit links
* :api-class:`\TYPO3\CMS\Extbase\Routing\ExtbasePluginEnhancer`
* :api-class:`In main <api-dev:\TYPO3\CMS\Extbase\Routing\ExtbasePluginEnhancer>`
* :api-class:`In 11.5 <api-11:\TYPO3\CMS\Extbase\Routing\ExtbasePluginEnhancer>`
* :api-class:`\TYPO3\CMS\Core\EventDispatcher\EventDispatcher
<api:\TYPO3\CMS\Core\EventDispatcher\EventDispatcher>`
The links then look like this:
Explicit links can use the interlink scheme to link to different TYPO3 versions. If not specified they also link to the typo3-core-preferred.
If you want to link directly to the source files on GitHub, you can use the :t3src: text role.
Implicit links have the advantage that they show more information about the class or interface in a popover while they still offer a link to the API.
.. Implicit links using the :php: text role:
* :php:`\TYPO3\CMS\Adminpanel\Controller\AjaxController`
* :php:`\TYPO3\CMS\Core\Http\Dispatcher`
* :php:`\TYPO3\CMS\Adminpanel\ModuleApi\ContentProviderInterface`
* :php:`\TYPO3\CMS\Backend\Search\LiveSearch\SearchDemand\DemandPropertyName`
* :php:`\TYPO3\CMS\Backend\Form\Behavior\OnFieldChangeTrait`
* :php:`\Psr\Log\LoggerInterface`
* :php:`\TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper`
* :php:`\MyVendor\MyExtension\FooBar`
* :php:`\Foo\Bar\Something`
.. prevent help text being displayed
`This\Is\No\Class`
The links then look like this:
\TYPO3\CMS\Adminpanel\Controller\AjaxController
\TYPO3\CMS\Core\Http\Dispatcher
\TYPO3\CMS\Adminpanel\ModuleApi\ContentProviderInterface
\TYPO3\CMS\Backend\Search\LiveSearch\SearchDemand\DemandPropertyName
\TYPO3\CMS\Backend\Form\Behavior\OnFieldChangeTrait
\Psr\Log\LoggerInterface
\TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper
\MyVendor\MyExtension\FooBar
\Foo\Bar\Something This\
As you can see, only links to the namespace /TYPO3/ can be linked to the
API. We do display general information about some other namespaces that are
commonly used in TYPO3 development. Example namespaces should always start with
\MyMyVendorMyExtension` for extensions and
`MyVendorMySitepackage` for sitepackages.
Implicit links are always referring to your typo3-core-preferred as set in the guides.xml.
Using the text role php- you can display the short name of the class
or interface within the text. Other then that it works just like the
:php: text role.
.. Short PHP class names, still linking to the API:
* :php-short:`\TYPO3\CMS\Adminpanel\Controller\AjaxController`
* :php-short:`\TYPO3\CMS\Core\Http\Dispatcher`
* :php-short:`\TYPO3\CMS\Adminpanel\ModuleApi\ContentProviderInterface`
* :php-short:`\TYPO3\CMS\Backend\Search\LiveSearch\SearchDemand\DemandPropertyName`
* :php-short:`\TYPO3\CMS\Backend\Form\Behavior\OnFieldChangeTrait`
* :php-short:`\Psr\Log\LoggerInterface`
* :php-short:`\TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper`
* :php-short:`\MyVendor\MyExtension\FooBar`
* :php-short:`\Foo\Bar\Something`
The links then look like this:
AjaxController
Dispatcher
ContentProviderInterface
DemandPropertyName
OnFieldChangeTrait
\LoggerInterface
\AbstractViewHelper
\FooBar
\SomethingYou can use the text role
:composer: to create an infobox with information
and links to Packagist. This way you can link to any TYPO3 extension
that is also listed on Packagist like
georgringer/news
and
b13/container
, any TYPO3 system extension like
typo3/cms-adminpanel
and any other Composer package like
typo3/testing-framework
:
This way you can link to any TYPO3 extension
that is also listed on packagist like :composer:`georgringer/news` and
:composer:`b13/container`, any TYPO3 system extension like
:composer:`typo3/cms-adminpanel` and any other Composer package like
:composer:`typo3/testing-framework`If you want to link to the TYPO3 Extension Repository (TER) you can use the
text role
t3ext instead and link extensions like EXT:news or
system extensions like EXT:adminpanel:
You can use the text role `t3ext` instead and link extensions like
:t3ext:`news` or system extensions like :t3ext:`adminpanel`Any file within the TYPO3 Core can be linked to their source file on GitHub using
the text role
t3src.
You can link classes like the EXT:core/Classes/Pagination/SlidingWindowPagination.php (GitHub) and any other file type like EXT:core/Resources/Private/Templates/ErrorPage/Error.html (GitHub).
You can link classes like the
:t3src:`typo3/sysext/core/Classes/Pagination/SlidingWindowPagination.php`
and any other file type like
:t3src:`typo3/sysext/core/Resources/Private/Templates/ErrorPage/Error.html`.You can link the following elements in any TYPO3 manual: Headlines, confvals and phpdomain definitions. It is also possible to put an anchor almost anywhere and then link it.
When an element in a manual can be linked a link symbol will appear when you hover it:
Hover over a headline to see if it is linkable, then click the link icon
After you click the link icon you can copy the reST link from the modal that appears:
Copy the reST reference
The reST code of the reference looks like this:
:ref:`Hide detail page in URL <georgringer/news:hideDetailPage>`A reference has the following syntax:
:ref:`[link_text] <[interlink]:[anchor]>`If you are linking within the same manual you can omit the [interlink]: part,
including the colon.
:ref:`Hide detail page in URL <hideDetailPage>`If there is a warning box displayed, that the link has no anchor, you can still link to it using a doc-reference:
Linking to a headline without an anchor
The link then looks like this in reST:
:doc:`Some further explanations <georgringer/news:Tutorials/BestPractice/HideDetailPage/Index#some-further-explanations>`However such a link would not work anymore if the section was moved to another page or if another section with the same headline was introduced.
We suggest adding a unique link anchor to the headline to be linked to in this case. See section Link anchors.
The renderer automatically converts simple URLs into links. This can be unintentional
in certain contexts, for example when using a
hypothetical domain like "example.org" or
placeholders instead of real query parameters
in a tutorial.
To prevent linking, the TYPO3 documentation uses the :samp: directive
to wrap the URL.
For example:
The TYPO3 backend can be accessed via :samp:`https://example.org/typo3` ..is rendered like:
The TYPO3 backend can be accessed via https:// ..
To emphasize parts of the URL, use curly braces:
The *route* is the "speaking URL" as a whole without the domain part,
for example :samp:`https://example.org/<page-path>/{<page-name>}`.is rendered like:
The route is the "speaking URL" as a whole without the domain part,
for example https://.
The TYPO3 documentation uses a defined set of dummy domains when describing URLs where the domain name does not matter, but serves as a placeholder. The defined set is
https://example.org https://example.com https://example.net – in this order: https:// as the preferred domain, and
https:// and https:// as alternatives if
multiple domains are required in the same context.
Why is https:// not preferred, as common sense would have it?
Because the preference for .org over .com fits with the fact
that the TYPO3 documentation is hosted on https:// and the
TYPO3 Association is owning the TYPO3 GmbH.
For explicit mention of the local development context it uses
https://example.localhost .If you need additional dummy domains, use subdomains of the domains listed
above such as https:// and
https://.
For example:
The class :php:`MailMessage` can be used to generate and send a mail without
using Fluid:
.. code-block:: rst
$mail = GeneralUtility::makeInstance(\TYPO3\CMS\Core\Mail\MailMessage::class);
$mail
->from(new Address('john.doe@example.org', 'John Doe'))
->to(
new Address('receiver@example.com', 'Max Mustermann'),
new Address('other@example.net')
)Important
Do not use this mechanism (external links) for links to sections of the TYPO3. Use references as described in the section above: References to TYPO3 manuals.
An URL that is mentioned within a text is automatically linked:
Lorem Ipsum Dolor https://example.org dolor sitThe result looks like this:
Lorem Ipsum Dolor https://example.org dolor sit
If you want to also give the URL a distinctive link text you can use the following syntax:
Lorem Ipsum Dolor `Example Page <https://example.org>`__ dolor sitThe result looks like this:
Lorem Ipsum Dolor Example Page dolor sit
Sometimes links can get quite long and unruly to use within the text. You can use so called named links to separate the link definitions from the text:
Lorem Ipsum Dolor `Example Page`_ dolor sit
.. _Example Page: https://example.orgThe result looks like this:
Lorem Ipsum Dolor Example Page dolor sit
Source: :
.. rst-class:: bignums-xxl
1. One one one bignums-xxl
Lots of stories here ...
...How it looks:
ONE One one bignums-xxl
Lots of stories here ...
TWO Two two
Lots of stories here ...
THREE Three three
Source: :
.. rst-class:: bignums
1. ONE One one
Delicious, JamesHow it looks:
ONE One one
Delicious, James.
Thank you, Miss Sophie, glad you enjoyed it. Little bit of North Sea haddock, Miss Sophie.
I think we'll have white wine with the fish.
TWO Two two
More ...
THREE Three three
More ...
Uses the same color as background, that is used in a tip textblock.
Source: :
.. rst-class:: bignums-tip
1. ONE One one bignums-tip
More ...How it looks:
ONE One one bignums-tip
More ...
TWO Two two
More ...
THREE Three three
More ...
Source: :
.. rst-class:: bignums-attention
1. ONE One one bignums-attention
More ...How it looks:
ONE One one bignums-attention
More ...
TWO Two two
More ...
THREE Three three
More ...
Source: :
.. rst-class:: bignums-important
1. ONE One one bignums-important
More ...How it looks:
ONE One one bignums-important
More ...
TWO Two two
More ...
THREE Three three
More ...
Source: :
.. rst-class:: bignums-warning
1. ONE One one bignums-warning
More ...How it looks:
ONE One one bignums-warning
More ...
TWO Two two
More ...
THREE Three three
More ...
Source: :
.. rst-class:: bignums-xxl
1. ONE One one bignums-xxl
This is the story of my life ...
.. rst-class:: bignums
1. When I was young
#. this
#. and that
#. and thisHow it looks:
ONE One one bignums-xxl
This is the story of my life ...
When I was young
When I was grown
Oops, ...
When I was old
Oh dear, ...
Prepare
Check the requirements
Is abc installed? Run:
which abcbcd available?Install
Now the actual stuff.
Abc
Bcd
Cde
Cleanup
BEWARE:
Be a happy user!
This section contains information on bullet lists and numbered lists. A text block which begins with a "*", "+", "-", "•", "‣", or "⁃", followed by whitespace, is a bullet list item.
* or - and 3 spaces after itBullet lists:
* or - and 3 spaces after itNumbered lists:
#. and 1 space after it for automatic numberingSee also:
* item 1
* item 2 is a longer text with line breaks. We can format and
indent like this
* item 3
* subitem 3.1
* subitem 3.2
* item 4How it looks:
item 3
Note
Empty lines before and after the sublist are mandatory.
This list style is used in TYPO3 documentation to style the explanation and description of parameters. The general markup we use is that of a "definition list".
An example with a standard styling would look like this:
Source:
parameterAbc
Condition: required, Type: string, Default: ''
Text describing parameterAbc ...
parameterBcd
Condition: optional, Type: boolean, Default: false
Text describing parameterBcd ...
Rendering result:
Condition: required, Type: string, Default: ''
Text describing parameterAbc ...
Condition: optional, Type: boolean, Default: false
Text describing parameterBcd ...
This markup works but isn't very readable due to the lack of styling.
Source:
.. rst-class:: dl-parameters
parameterAbc
:sep:`|` :aspect:`Condition:` required
:sep:`|` :aspect:`Type:` string
:sep:`|` :aspect:`Default:` ''
:sep:`|`
Text describing parameterAbc ...
parameterBcd
:sep:`|` :aspect:`Condition:` optional
:sep:`|` :aspect:`Type:` boolean
:sep:`|` :aspect:`Default:` false
:sep:`|`
Text describing parameterBcd ...
Rendering result:
| Condition: required
| Type: string
| Default: ''
|
Text describing parameterAbc ...
| Condition: optional
| Type: boolean
| Default: false
|
Text describing parameterBcd ...
Explanation:
Right in front of the definition list we place an 'rst-class' directive
with 'dl-parameters', meaning a definition list style for parameters.
As a result the rendered html construct will look like
<dl class="dl-. The first line of the description
is used for multiple "keyword: value" explanations. As a separator
we are using the vertical bar. And we are using a special text role
"sep" (for separator) for it. As a result it will be rendered as
<span class="sep">. The "keyword:" part is marked up specially
as well just to give it the ":aspect:" text role Our css uses the classes to
give the whole construct a nice styling.
Attention:
The text roles ascpect and sep (for separator) need to be defined. The usual
way of defining them is by having these lines in the
Documentation/ file. Add these lines:
.. role:: aspect (emphasis)
.. role:: sep (strong)Sphinx already comes with standard text roles 'emphasis' and 'strong'. 'aspect' and 'sep' inherit their properties and are further specialized.
Let's say you want to place labels in front of each definition list item. This creates anchors you can link to symbolically with the Sphinx "instersphinx" procedure. A downside is that this will intercept the list. Instead, many lists are created. This isn't a problem, if you repeat the 'rst-class' line.
Source:
.. _label-parameterAbc:
.. rst-class:: dl-parameters
parameterAbc
:sep:`|` :aspect:`Condition:` required
:sep:`|` :aspect:`Type:` string
:sep:`|` :aspect:`Default:` ''
:sep:`|`
Text describing parameterAbc ...
.. _label-parameterBcd:
.. rst-class:: dl-parameters
parameterBcd
:sep:`|` :aspect:`Condition:` optional
:sep:`|` :aspect:`Type:` boolean
:sep:`|` :aspect:`Default:` false
:sep:`|`
Text describing parameterBcd ...
Rendering result:
| Condition: required
| Type: string
| Default: ''
|
Text describing parameterAbc ...
| Condition: optional
| Type: boolean
| Default: false
|
Text describing parameterBcd ...
Link example:
Source:
Here we link to :ref:`A link text for parameterAbc <label-parameterAbc>`.
Here we link to :ref:`A link text for parameterBcd <label-parameterAbc>`.
Result:
Here we link to A link text for parameterAbc.
Here we link to A link text for parameterBcd.
You can use the directive .. directory- to make a nested list look like
an expandable directory tree. This is helpful in discussing file structure for
extensions or projects.
.. directory-tree::
:level: 2
:show-file-icons: true
* EXT:my_sitepackage/Resources/Private/Templates/
* Layouts
* Default.html
* WithoutHeader.html
* Pages
* Default.html
* StartPage.html
* TwoColumns.html
* With_sidebar.html
* Partials
* Footer.html
* Sidebar.html
* Menu.htmlClasses
Backend
Persistence
TCA
TsConfig
TypoScript
Icons.php
page.tsconfig
Services.yaml
user.tsconfig
Documentation
Language
Public
Tests
composer.json
ext_emconf.php
ext_localconf.php
ext_tables.sql
.. directory-tree::
* :path:`Classes`
* :path:`Configuration`
* :path:`Backend`
* :path:`Extbase`
* :path:`Persistence`
* :path:`TCA`
* :path:`TsConfig`
* :path:`TypoScript`
* :file:`Icons.php`
* :file:`page.tsconfig`
* :file:`Services.yaml`
* :file:`user.tsconfig`
* :path:`Documentation`
* :path:`Resources`
* :path:`Private`
* :path:`Language`
* :path:`Public`
* :path:`Tests`
* :file:`composer.json`
* :file:`ext_emconf.php`
* :file:`ext_localconf.php`
* :file:`ext_tables.sql`Limit the levels of the tree initially shown expanded.
Display a folder icon beside each entry that has a sub-entry, a file icon otherwise.
Attention
Pitfall!
With pure Docutils the directive for specifying CSS classes is class.
With Sphinx you have to use .. rst- instead because class
is already used in the Sphinx-Python-domain.
The t3SphinxThemeRtd theme for TYPO3 comes along with style that make
the items of an unordered list appear as "buttons". To put this into
action the <ul> tag needs to have one of the following (css-) classes.
To assign a class place a .. rst- right in front of
the list like so:
.. rst-class:: horizbuttons-attention-m
* horizbuttons-attention-m
* two
* three `with link <#>`__Like admonition attention (blue)
Like admonitions error, important (yellow)
Like admonitions generic, note, see also (neutral, grey)
Use the primary = key color (TYPO3 orange)
Shall be very striking and unusual, something to not be be overseen.
Like admonitions hint, tip (green)
Like admonitions caution, danger, warning (red)
Like admonition attention (blue)
Like admonitions error, important (yellow)
Like admonitions generic, note, see also (neutral, grey)
Use the primary = key color (TYPO3 orange)
Shall be very striking and unusual, something to not be be overseen.
Like admonitions hint, tip (green)
Like admonitions caution, danger, warning (red)
Like admonition attention (blue)
Like admonitions error, important (yellow)
Like admonitions generic, note, see also (neutral, grey)
Use the primary = key color (TYPO3 orange)
Shall be very striking and unusual, something to not be be overseen.
Like admonitions hint, tip (green)
Like admonitions caution, danger, warning (red)
Source: :
#. abc
#. bcd
#. cdeHow it looks
See also Styled numbered sections (bignums).
Each reST document must have a title. It is overlined and underlined like this:
.. _rest-cheat-sheet:
=============================
Cheat sheet: reStructuredText
=============================The anchor is used for permalinks. It should be lowercase with dashes between words. During rendering special signs are converted into dashes and all letters changed to lowercase if you ignore this.
Use headers to divide your document into sections. Start with h2:
By convention we use the following underlines:
.. _rest-cheat-sheet:
=============================
Cheat sheet: reStructuredText
=============================
Some text.
.. _h2-headline:
H2 Headline
===========
Lorem Ipsum
.. _h3-headline:
H3 Headline
-----------
Some more text
Further headline levels are possible:
.. _h4-headline:
H4 Headline
~~~~~~~~~~~
.. _h5-headline:
H5 Headline
"""""""""""
.. _h6-headline:
H6 Headline
'''''''''''
.. _another-h2-headline:
Another H2 Headline
===================They look like this:
The underlining special signs should be as long as the line but this is not enforced.
Each headline should have an anchor. Otherwise permalinking does not work.
In the official docs recommend to never delete an anchor. If a concept is removed without substitute, move the anchor to a special page when and why the concept was removed.
Includes can be used for two use cases in the documentation: Repeating text snippets used in several places or breaking up long pages into easier to edit subparts.
Some documentation projects have the same snippet of text appear in several places. This text can be maintained once and included in many places.
In this case it may make sense to include text snippets. The .. include:: some
directive does this.
Files to be included cannot lie outside the Documentation folder.
They may not end on .rst. By convention they should end on .rst..
Table of contents
Include the same text asking for contributions in all Events that do not have an example yet:
Example
=======
.. include:: /_includes/EventsContributeNote.rst.txtExample
=======
.. include:: /_includes/EventsContributeNote.rst.txtThe file to be included:
.. note::
Currently, we do not have an example for this event. If you can provide a
useful one, please open an issue ...These rst definitions will be included in all places the include is used as if they had been written directly into the rst file. All markup is respected.
In places like the TSconfig reference or TCA reference it is helpful to display all properties of an element on one page. However this gives the contributors very large rst files to maintain. Such files can be broken into pieces that contain only the definition and maybe example of one parameter each.
Properties of the TCA column type `category`
============================================
.. confval-menu::
:display: table
:type:
:Scope:
.. include:: _Properties/_Default.rst.txt
:show-buttons:
.. include:: _Properties/_ExclusiveKeys.rst.txt
:show-buttons:
.. include:: _Properties/_ForeignTable.rst.txt
:show-buttons:Each include file in turn contains the complete data for one property, for example:
.. _columns-category-properties-exclusivekeys:
.. confval:: exclusiveKeys
:name: category-exclusiveKeys
:type: string (list of)
List of keys that exclude any other keys ...The option :show- display a special "Edit on GitHub" button only for
the section contained within include:
The edit on GitHub button of an included section
| Name | Type | Scope |
|---|---|---|
| string, local file path, relative or absolute | ||
| string, local file path, relative or absolute |
Path to the file to be included. Can be relative or absolute.
.. include:: /some/absolute/path/_includes/_SomeFile.rst.txt
.. include:: ../_includes/_SomeFile.rst.txtThe path is calculated starting from the Documentation directory.
It is not possible to include files from different locations in an extension.
If set an edit on GitHub Button is displayed if the edit-on-github workflow is enabled in the guides.xml. In future other buttons might be displayed if configured in the guides.xml.
Usually it is desired to have each and every .rst- file appear in the menu somewhere. The rendering tool issues warnings if a file is not included.
Hint
If really needed, an .rst file may be tagged as :orphan: right at the beginning. This will suppress the warning.
:orphan:Displays a box to the right of the current paragraph. The box is mostly used at the top of a page for quick navigation:
.. sidebar:: reST content elements
* :ref:`Cards <rest-cards>`
* :ref:`Tabs <rest-tabs>`
* :ref:`Configuration values <rest-confval>`In the official documentation files we try to follow the following coding guidelines:
.. include:: /Includes.rst.txt to display
global messages, for example for outdated versions.:navigation-title: My Title at the top
of each file to provide a shorter title to be displayed in the menu.
See Navigation title: A page title displayed in menus.:navigation-title: Introduction
.. include:: /Includes.rst.txt
.. _introduction:
=====================
Introduction to MyExt
=====================
This extension provides a simple way to display weather data.
* It fetches data from an external API and processes it in a way that allows
it to be cached and reused efficiently throughout the TYPO3 site.
* The results are cached for performance.
* You can configure the output in the backend.
This extension is compatible with TYPO3 v12 and above.
:navigation-title: Installation
.. include:: /Includes.rst.txt
.. _installation:
========================================
Installation and usage of this extension
========================================
You can install the extension like this:
.. code-block:: bash
composer install myvendor/my-extension
.. _config:
Create a configuration file
===========================
If you want to see a more complete configuration, refer to the example below:
.. literalinclude:: _codesnippets/_config.yaml
:caption: EXT:my_ext/Configuration/MyConfig/config.yaml
=, headlines of level 2 are underlined with =,
level 3 with - and level 4 with ~... _rest-cheat-sheet:
=============================
Cheat sheet: reStructuredText
=============================
Some text.
.. _h2-headline:
H2 Headline
===========
Lorem Ipsum
.. _h3-headline:
H3 Headline
-----------
Some more text
See Headlines and Anchors for more headline levels.
This page explains the general file structure of a TYPO3 documentation that can be rendered with the rendering toolchain.
Table of Contents:
In order for the documentation to be rendered, you need at least
And one of the following files:
Further conventions are:
.rst.txt .Documentation/GeneralConventions/FileStructure.rst .Index.rst it is used as
fallback if a page is not found during switching versions._Services.yaml .To render a complete documentation manual you need a folder called
Documentation with at least a reStructured Text file as entry point named
Documentation\ and a configuration file called
Documentation\. Add more files as needed.
You can keep a README. or README. file with basic
information and a link to the published manual in the root folder of the
extension. These files will be commonly displayed on GitHub and GitLab.
Documentation/Index.rst The documentation start page (Documentation/) is the entry
point of the main documentation. It usually contains general information about
the manual, a summary of its purpose and a table of contents that refers to
further pages.
The start page should contain an anchor target
.. _ above its
document title. This way you can link to a documents start page by:
See :ref:`TYPO3 Explained <t3coreapi:start>`.If your manual has more pages then this start page it must contain a table of content
directive called
.. toctree::. The toctree on the start page
defines which pages will be displayed in main navigation of the rendered
manual.
Documentation/Sitemap.rst The Sitemap. contains the sitemap of the documentation.
It is an almost empty file that is automatically filled during rendering.
:template: sitemap.html
.. include:: /Includes.rst.txt
=======
Sitemap
=======
.. The sitemap.html template will insert here the page tree automatically.Documentation/guides.xml This file contains the metadata and configuration for the rendering with the TYPO3 theme.
Read more about the Configuration of the rendering - guides.xml.
Hint
If you are migrating from the legacy Sphinx-based rendering and still have
a Documentation/ you can use an automatic migration
tool to migrate the settings.cfg into a guides.xml.
Example:
<?xml version="1.0" encoding="UTF-8"?>
<guides xmlns="https://www.phpdoc.org/guides" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://www.phpdoc.org/guides ../vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
links-are-relative="true"
default-code-language="php"
>
<extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
project-home="https://extensions.typo3.org/extension/news/"
project-contact="https://typo3.slack.com/archives/C03TG7QJT"
project-repository="https://github.com/georgringer/news"
project-issues="https://github.com/georgringer/news/issues"
project-discussions="https://github.com/georgringer/news/discussions"
edit-on-github-branch="main"
edit-on-github="georgringer/news"
typo3-core-preferred="11.5"
interlink-shortcode="georgringer/news"
/>
<project title="News system"
version="local"
copyright="since 2010 by Georg Ringer & Contributors"
/>
<inventory id="t3extbasebook" url="https://docs.typo3.org/m/typo3/book-extbasefluid/10.4/en-us/"/>
</guides>
The TYPO3 documentation rendering pipeline supports rendering of CommonMark Markdown plus a few additional constructs like tables.
The main entry point for Markdown documentation must be
Documentation/. Each folder in the Documentation directory
should contain a file called Index. if it contains Markdown at all.
<?xml version="1.0" encoding="UTF-8" ?>
<guides
xmlns="https://www.phpdoc.org/guides"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://www.phpdoc.org/guides vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
input-format="md"
index-name="Index"
automatic-menu="true"
>
<project title="My Extension" />
<extension
class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
edit-on-github="myvendor/my-extension"
edit-on-github-branch="main"
interlink-shortcode="myvendor/my-extension"
project-home="https://github.com/myvendor/my-extension"
project-issues="https://github.com/myvendor/my-extension/issues"
project-repository="https://github.com/myvendor/my-extension"
typo3-core-preferred="stable"
/>
</guides>
Lines 6-8 are different from reST documents.
Index.md to be added.For third-party TYPO3 extensions that do not require extended documentation
you can also publish a README. or README. to
https://docs.typo3.org/
For this workflow the README MUST be situated in the
extension's root folder. The :file:`Documentation/' folder can then be omitted.
For single file documentation, the README. 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
======
..
.. csv-table::
:header: "", "URL"
**Repository:**, :samp:`https://{<vcs-repository>}`
**Read online:**, :samp:`https://docs.typo3.org/p/{<package-name>}/main/en-us/`
**TER:**, :samp:`https://extensions.typo3.org/extension/{<extension-key>}/`<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>/ |This XML file contains meta information and configuration used during rendering of a manual.
<?xml version="1.0" encoding="UTF-8"?>
<guides xmlns="https://www.phpdoc.org/guides" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://www.phpdoc.org/guides ../vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
links-are-relative="true"
default-code-language="php"
>
<extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
project-home="https://extensions.typo3.org/extension/news/"
project-contact="https://typo3.slack.com/archives/C03TG7QJT"
project-repository="https://github.com/georgringer/news"
project-issues="https://github.com/georgringer/news/issues"
project-discussions="https://github.com/georgringer/news/discussions"
edit-on-github-branch="main"
edit-on-github="georgringer/news"
typo3-core-preferred="11.5"
interlink-shortcode="georgringer/news"
/>
<project title="News system"
version="local"
copyright="since 2010 by Georg Ringer & Contributors"
/>
<inventory id="t3extbasebook" url="https://docs.typo3.org/m/typo3/book-extbasefluid/10.4/en-us/"/>
</guides>
Table of Contents:
If you start a new documentation guide, for example in a TYPO3 extension, use the
init command:
docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest initAnd follow the interactive question.
Hint
If you are migrating from the legacy Sphinx-based rendering and still have
a Documentation/ you can use an automatic migration
tool to migrate the Settings.cfg into a guides.xml
The
<guides> tag is the root tag of the Documentation/.
It is used for general configuration during parsing and rendering.
The following settings can be relevant for TYPO3 themed documentation:
Can be used to set the code-language that should be used for code-blocks if no language is set.
We advice to set the language to be used in each code-block however.
typoscript as default language for code-blocks<?xml version="1.0" encoding="UTF-8"?>
<guides xmlns="https://www.phpdoc.org/guides" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://www.phpdoc.org/guides ../vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
default-code-language="typoscript"
>
<!-- [...] -->
</guides>The changelog (documentation of the extension "core") consists of several thousands of pages. The reason is that very long lists of changelog entries in the menu are not helpful to the user and slow down the search.
<?xml version="1.0" encoding="UTF-8"?>
<guides xmlns="https://www.phpdoc.org/guides" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://www.phpdoc.org/guides ../vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
max-menu-depth="2"
>
<!-- [...] -->
</guides>The
<inventory> tag is located directly in the guides tag.
There can be 0 or more
<inventory> tags, each defines one Interlink
inventory.
A list of globally available Interlink (formerly "Intersphinx") repositories can be found in Available default inventories
It is possible, though rarely needed to define custom interlink mappings:
For example:
<inventory id="sphinx" url="https://www.sphinx-doc.org/en/master/"/>The
<project> tag is located directly in the guides tag.
There can be 0 or 1 tag of that name.
This tag can contain the following meta information:
The project tag 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.
For TYPO3 extensions we suggest to use the extension name in a readable format:
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 reference<Topic> Tutorial, e.g. "Editors Tutorial",
for collections of tutorials on a specific topic<?xml version="1.0" encoding="UTF-8"?>
<guides xmlns="https://www.phpdoc.org/guides" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://www.phpdoc.org/guides ../vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
>
<project title="News system"
version="local"
copyright="since 2010 by Georg Ringer & Contributors"
/>
</guides>When documentation is rendered in the GitHub action for deployment onto
https://docs.typo3.org the version is set automatically to the extension's
version derived from the Git tag. Setting the version in the
guides. only affects local rendering.
You can set the release property to the release number of your
document and output this value using
|release within
your text if you desire to. Usually it is not used.
The copyright attribute contains the copyright claim of the project. It is displayed in the footer as "© Copyright <copyright>" and has in most use cases in 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 John Doe & contributors" (third-party TYPO3 extensions)The
<extension> tag is located directly in the guides tag.
TYPO3 Theme specific settings can be made in the tag
<extension class="\.
There can be 0 or more tags of that name, however only one
<extension> tag
should be defined for the TYPO3 documentation theme.
The class attribute is mandatory, it references the extension that is used to render the documentation with the TYPO3 documentation theme.
The github_repository and github_branch attributes should 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 welcome, these attributes 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".For example:
<extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
edit-on-github-branch="main"
edit-on-github="TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument"
/>""
If this configuration is set, a button "Edit on GitHub" is displayed on each page of the manual.
<?xml version="1.0" encoding="UTF-8"?>
<guides xmlns="https://www.phpdoc.org/guides" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://www.phpdoc.org/guides ../vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
>
<extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
edit-on-github-branch="main"
edit-on-github="georgringer/news"
/>
</guides>main
The branch that should be used for the "Edit on GitHub" button.
<?xml version="1.0" encoding="UTF-8"?>
<guides xmlns="https://www.phpdoc.org/guides" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://www.phpdoc.org/guides ../vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
>
<extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
edit-on-github-branch="master"
edit-on-github="FriendsOfTYPO3/tt_address"
/>
</guides>Documentation
The directory in which the documentation can be found. The GitHub render
action currently does not support using other directories
then Documentation/.
This setting is used exclusively for system extension manuals as the TYPO3 Core is kept in a mono repository on GitHub.
<?xml version="1.0" encoding="UTF-8"?>
<guides xmlns="https://www.phpdoc.org/guides" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://www.phpdoc.org/guides ../vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
>
<extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
edit-on-github-branch="main"
edit-on-github="typo3/typo3"
edit-on-github-directory="typo3/sysext/adminpanel/Documentation/"
/>
</guides>somemanual
The interlink shortcode will be displayed in the "Reference this headline" dialog when users click on the link symbol beside a headline or other linkable element.
These references can be used to link to your manual from other documents rendered with the TYPO3 theme. However they will only work if you follow these rules:
georgringer/news typo3/cms-adminpanel 
Reference a headline in the EXT:news manual
The project-<topic> attributes provide all links with the name "<Topic>" in the footer of the documentation that guide the user to other aspects of the project than the documentation, for example to the project page in the TYPO3 Extension Repository (TER):
is set to the homepage URL of the project. For official TYPO3 manuals this is the public base URL at docs.typo3.org, for public TYPO3 extensions this is the associated TER page or a custom project website, for example
https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ orhttps://extensions.typo3.org/extension/news .is usually set to an email address or Slack channel URL of the team behind the project, for example
mailto:documentation\@typo3.org orhttps://typo3.slack.com/archives/C028JEPJL .is set to the repository of the project's VCS, for example
https://github.com/FriendsOfTYPO3/extension_builder .is set to the location where project issues are to be created and edited, for example
https://github.com/FriendsOfTYPO3/extension_builder/issues is used in the rare case that project-related discussions take place in locations other than those defined by the project-contact and project-issues attributes, for example
https://github.com/FriendsOfTYPO3/extension_builder/discussions .<?xml version="1.0" encoding="UTF-8"?>
<guides xmlns="https://www.phpdoc.org/guides" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://www.phpdoc.org/guides ../vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
>
<extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
project-home="https://extensions.typo3.org/extension/news/"
project-contact="https://typo3.slack.com/archives/C03TG7QJT"
project-repository="https://github.com/georgringer/news"
project-issues="https://github.com/georgringer/news/issues"
/>
</guides><?xml version="1.0" encoding="UTF-8"?>
<guides xmlns="https://www.phpdoc.org/guides" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://www.phpdoc.org/guides ../vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
>
<extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
project-home="https://extensions.typo3.org/extension/adminpanel/"
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"
/>
</guides><?xml version="1.0" encoding="UTF-8"?>
<guides xmlns="https://www.phpdoc.org/guides" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://www.phpdoc.org/guides ../vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
>
<extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
project-home="https://docs.typo3.org/m/typo3/reference-tsconfig/main/en-us/"
project-contact="https://typo3.slack.com/archives/C028JEPJL"
project-repository="https://github.com/TYPO3-Documentation/TYPO3CMS-Reference-TSconfig"
project-issues="https://github.com/TYPO3-Documentation/TYPO3CMS-Reference-TSconfig/issues"
/>
</guides>none/SomePath/MyIssueReport https://github.com/MyVendor/MyProject/issues/new https://gitlab.com/myvendor/myproject/-/issues/new https://forge.typo3.org/projects/typo3cms-core/issues/new For security reasons arbitrary URLs are not allowed. If you use
a private Gitlab or another issue tool, Make an internal page and
link it like /Some.
stable
You can set the preferred TYPO3 Core version. This version is used to determine the desired version for links to other manuals and system extensions.
<extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
typo3-core-preferred="stable" />If no preferred version is set it defaults to stable. Possible values are:
main, stable (latest LTS), oldstable (old LTS) or an explicit LTS / eLTS
version like 12. or 8..
At the time of writing the extension EXT:news is compatible with TYPO3 v11.5 and v12.4. When referencing Core manuals or extensions, we want the links to go automatically to version 11.5 of that reference or core extension. Therefore we set the preferred TYPO3 Core version to that value:
<?xml version="1.0" encoding="UTF-8"?>
<guides xmlns="https://www.phpdoc.org/guides" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://www.phpdoc.org/guides ../vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
>
<extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
typo3-core-preferred="11.5"
</guides>If you want your links to always go to the latest stable long time support version (LTS) of the TYPO3 Core, you can set typo3-core-preferred to stable.
At the time of writing references to official manuals and Core extensions will be rendered to version 12.4. Once TYPO3 13 LTS is released they will automatically switch to the according version on next re-rendering.
<?xml version="1.0" encoding="UTF-8"?>
<guides xmlns="https://www.phpdoc.org/guides" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://www.phpdoc.org/guides ../vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
>
<extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
typo3-core-preferred="stable"
</guides>For local rendering you can use the following command in the directory that
contains the Documentation folder:
docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --config=DocumentationOpen the file saved to Documentation- in a
browser of your choice.
Use the init command to start writing TYPO3 documentation.
docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest initThis command creates a guides.xml
configuration file and some example pages in folder Documentation.
We have prepared a Docker container that you can use to create screenshots for the official documentation, which already follows out Guidelines for screenshots.
Table of content
See also
You can run the screenshot project locally using the prebuilt Docker image:
docker run -d --name typo3-screenshots -p 8080:80 linawolf/typo3-screenshots
# Follow the logs to track progress:
docker logs -f typo3-screenshotsOnce setup is complete, open:
Note
The container resets on every run. It is ideal for reproducible test environments and fresh screenshots.
To start fresh, you can stop and remove the running container, then launch it again.
docker stop typo3-screenshots
docker rm typo3-screenshots
docker run -d --name typo3-screenshots -p 8080:80 linawolf/typo3-screenshotsThis gives you a clean TYPO3 instance every time.
You can access the container's shell to explore the file system, install additional extensions, or run TYPO3 CLI commands:
docker exec -it typo3-screenshots bashThis drops you into a terminal session inside the container.
After accessing the container shell, you can exit at any time by typing:
exitThis will close the interactive shell session and return you to your host terminal.
Once inside the container (via Accessing the container shell), you can install TYPO3 extensions using Composer. For example:
composer require typo3/cms-lowlevelThen you can run the setup command to register the extension:
./vendor/bin/typo3 extension:setupNote
Since the container resets every time, any installed extension will be lost on restart unless you build a new image with those extensions included. This is intentional to ensure a consistent environment for screenshots.
To run any TYPO3 CLI command inside the container, use:
docker exec -it typo3-screenshots ./vendor/bin/typo3 <command>Examples:
docker exec -it typo3-screenshots ./vendor/bin/typo3 list
docker exec -it typo3-screenshots ./vendor/bin/typo3 extension:setup
docker exec -it typo3-screenshots ./vendor/bin/typo3 language:updateImportant
Always use indentation levels correctly. Your code may not be rendered as expected if you do not.
Note
Currently, the documentation is not always indented consistently. In some manuals, an indentation level of 3 spaces was used instead. We currently recommend to use what has been used on the page you are currently editing.
Example:
.. image:: /_Images/a4.jpg
:alt: Left floating image
:target: https://typo3.org
:class: with-shadowif in doubt about the length: use short lines!
Most of our documentation projects contain an .editorconfig file.
Use this file to setup your editor / IDE correctly. With some, everything will just work automatically. With others, you will need to download a plugin. This is explained on the Editorconfig page.
Sample contents of .editorconfig
# EditorConfig is awesome: http://EditorConfig.org
# top-most EditorConfig file? false = no!
root = false
[{*.rst,*.rst.txt}]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
indent_style = space
indent_size = 4
max_line_length = 80
# MD-Files
[*.md]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
indent_style = space
indent_size = 4
max_line_length = 80This sample .editorconfig will instruct your editor / IDE to:
The only way to include "special" characters is to use them directly
In reStructuredText it is possible to use any type of underlining. The first used will be recognized as level 1 etc.
However, adhering to the standard for TYPO3 documentation makes it easier for other contributors to find their way around a file and pick the correct underlining for the header level.
Use the conventions as defined in Headlines and anchors.
This underlining is used per (.rst) file. It does not matter where in the toctree the file is. You always start with underlining for level 1 (title) in each file:
========
1. Title
========
2. Header Level 1
=================
3. Header Level 2
-----------------
4. Header Level 3
~~~~~~~~~~~~~~~~~
5. Header Level 4
"""""""""""""""""
6. Header Level 5
'''''''''''''''''
7. Header Level 6
^^^^^^^^^^^^^^^^^
8. Header Level 7
#################
etc.Example, how you can point out deprecations:
.. deprecated:: 10.2
The hook shown here is deprecated since TYPO3 10.2 - use a custom
:ref:`PSR-15 middleware<request-handling>` instead.New feature:
.. versionadded:: 10.2
Starting with TYPO3 10.2 hooks and signals have been replaced by a PSR-14 based
event dispatching system.Changes:
.. versionchanged:: 2.3.1
This feature was changed ...For more information, see the open issue:
Linking to the changelog should not be necessary, if all relevant information has been transferred to the documentation, but it is not discouraged either.
The changelog has a title anchor, so you can easily link to it with :ref:.
:ref:`ext_core:feature-101544-1691063522`which outputs the link:
Feature: #101544 - Introduce PHP attribute to autoconfigure event listeners
For this to work, ext_ must be defined in Settings.:
ext_core = https://docs.typo3.org/c/typo3/cms-core/main/en-us/If you describe something that needs to be selected from a menu or other GUI element or clicked one after the other, use > as separator and use text role guilabel.
Important
Use the spelling of the word as used in the GUI!
Examples:
Select :guilabel:`File > Open`Click on :guilabel:`ADMIN TOOLS > Extensions` in the backend.When pointing out keyboard shortcuts or keystroke sequences, use text role kbd.
Example:
Press :kbd:`ctrl` + :kbd:`s`Use sentence case - this means the title and headers will be capitalized like normal sentences. The first word is always capitalized and the rest is spelled as they would in "normal text".
This is different from "TYPO3 content style guide" which capitalizes more words in the title. Capitalization in the documentation is still inconsistent currently, so you cannot rely on existing pages to show the correct convention.
Use common spelling for American English. Some specific TYPO3 terms have a special spelling. See Spelling, terms and glossary
The authoritative style guide for writing official text for TYPO3 is The TYPO3 Writing Style Guide on typo3.org.
Important
We use different title capitalization from the content style guide, to ease contribution. The main differences are explained below in Rules for titles & section headers.
This section aims to add some additional explanations and more examples for rules already defined in the style guide. It also explains how to apply the rules in the documentation (for example format with reST).
Since the English language is not always specific and there may be more than one correct spelling for some words, we have added a Spelling, terms and glossary. If something is not mentioned here specifically, use correct spelling in English language or rather American (US) language. Refer to the resources, which the style guide suggests, or use Merriam Webster (https://m-w.com) as last resort. If in doubt, ask in Slack channel #typo3-documentation (see Help and support).
We use "sentence case" for title case:
This is different from the content style guide where more words are capitalized (first and last word, all words with 4 letters and more, all principal words).
This was changed on February 4, 2020 for the following reasons:
This means, the same rules as in Rules for plain text apply to the titles.
For discussion, see Title capitalization in the docs (revisited)
Examples:
Important
This applies to all headers on a page, not just the top level header (title).
In reST, headers are created by underlining / overlining with (====, ----, etc.)
as described in Headlines and anchors:
=================
This is the title
=================
This is the subheader
=====================The same spelling rules as in the title apply to buttons and links.
If the text refers to terms used in the GUI (for example a clickpath for selecting something from the menu is described), the spelling used in the GUI should be used, for example "File > Open" or "click on "ADMIN TOOLS > Extensions".
See Referring to GUI elements for information about how to use reST markup for this.
Compound words (or compounds) are words that have been glued together from one or more separate words to create a new term with a new meaning as in backyard (back and yard) or New Age (new and age).
But how should they be spelled? Backend, back-end or back end? Site package or sitepackage?
All these spellings for backend are currently correct spellings (at least according to some sources.
Important
In the TYPO3 context we have defined backend to be the preferred spelling, as well as sitepackage.
If a spelling has been explicitly defined in the Spelling, terms and glossary, please use that spelling.
How can you decide for yourself in other edge cases?
Tip
If in doubt, use what is commonly used in the documentation. If you see inconsistencies between documentation and English dictionaries or within the documentation, raise the issue in Slack.
There are some edge cases and some terms are not spelled consistently throughout various resources. Often it also depends on the context. Capitalization may change over the course of time, for example see The Associated Press style guide will no longer capitalize 'internet'. In other texts, "internet" is still capitalized.
For this reason we have put together a spelling reference to list some common terms that may be difficult to spell or that are spelled differently in the TYPO3 context.
There are some specific TYPO3 spellings like TypoScript, TSconfig, stdWrap, ViewHelper, TYPO3, etc. These should be used! See Spelling, terms and glossary for more examples.
If you are using class names, function names, databases tables or fields, configuration options etc, use the spelling that is used in the source code.
Examples:
Often acronyms are written with capital letters only. If terms are commonly spelled that way, this is how we spell them as well, for example HTML, CMS, PHP or LTS.
General rules of the English language apply here:
If proper names or brand names (for example Coca-Cola) are used in normal text (not headlines), they are capitalized.
These can be countries, names of people, corporations or brand names.
Examples:
Some tools have a program, which you can run. For example, Git has the command line
tool git. When the documentation explicitly refers to the command git, its appropriate
spelling is used, which is lowercase. In all other cases, we use capital
spelling for Git, because it applies to the rules for Proper names, brand names.
The same goes for Docker, Composer, etc.
The content was moved to Spelling, terms and glossary.
In addition to the TYPO3 Content Style Guide, some other resources have been used:
Capitalization:
Compound words:
Important
The entire official documentation uses reST only. This includes the the Guides, Tutorials, "TYPO3 Explained", Reference, the Changelog and system extensions.
The rendering chain and tools are built and optimized to process reST markup. We recommend using this format for your documentation. As reST is more feature-rich, and you will benefit from the advanced features of the TYPO3 documentation toolchain.
The file ending of reST files is .rst.
When you started your documentation in markdown, you can convert it to reST using our migration tool.
However we do highly recommend using reST for your documentation, we also support markdown for your (extension) documentation. The file ending of markdown files is .md.
Our toolchain supports the commonmark dialect of markdown. This is a standardized version of markdown. We do not support other markdown dialects, although they might work. We cannot guarantee that they will work in the future. You can consult our Markdown reference for more information.
Victor Zverovich makes the comparison:
According to John Gruber, the inventor of Markdown, “Markdown’s syntax is intended for one purpose: to be used as a format for writing for the web.” and, in particular, it supports inline HTML. reStructuredText on the other hand is specifically designed for writing technical documentation.
readthedocs:
"It should be noted that Commonmark doesn’t support a lot of the concepts that RST lets you represent. In particular, there is no standardized way in Commonmark to represent inline or block levels constructs. So things like the toctree directive and :ref: markup don’t have an analog."
Read the Docs & Sphinx now support Commonmark (2015)
reST (with our Sphinx Toolchain)
+
-
Syntax may be unusual and rendering breaks if not done correctly, for example
Markdown
+
-
This section defines how to spell certain trademark and product names. For a list of the TYPO3 terminology and their short descriptions, see Spelling and TYPO3 Terminology.
A
Apache,
API,
B
backend,
blog post, blogger, blogging,
C
code sprint,
command line, run something at the command line,
command-, run a command-line spell-checker,
Changelog,
checkbox,
Composer,
Core Team, TYPO3 Core Team,
Core, TYPO3 Core,
Core extension,
cross-,
Crowdin,
CSV (comma separated values),
D
Data Processor,
DBAL,
Docker,
Docker Compose,
Doctrine,
Documentation Team, TYPO3 Documentation Team,
Data,
E
Edit on Git,
Edit on Git,
Edit on Git,
Extbase,
Extension Manager
extension,
F
Flex,
Fluid,
Form,
frontend,
frontend rendering,
G
Git,
Git,
H
how to document,
how-, a how-,
I
Inno,
Introduction Package,
L
Link,
Linux,
M
Markdown,
mark up the text,
markup ,
Maria,
My,
mac, outdated: Mac, Mac OS X,
model-,
MVC,
N
nginx,
O
Open Source,
P
page TSconfig,
Php,
PHPStan,
PHPUnit,
PHP CS Fixer,
PHP_,
PNG,
Postgre,
Q
quick start,
R
re, re,
richt text editor,
RTE,
S
sitepackage,
Sphinx,
style guide , Styleguide ,
SVG,
system extension (not: 'sys extension'),
T
TCA,
TCE,
TCEforms,
TCEmain,
textrole,
third party extension,
toctree,
TSconfig,
TYPO3,
TYPO3 Core, Core,
TYPO3 Core Engine,
TYPO3 Core Team, Core Team,
TYPO3 Core Engine,
TYPO3 v12, TYPO3 v12., TYPO3 v12 LTS, TYPO3 version 12,
Typo,
U
UNIX,
V
View,
W
Windows, Microsoft Windows,
windows, modal windows,
How to use these terms:
reST as abbreviation.For accessibility reasons always provide an alt text:
More option for embedding images into ReST: Images.
Note
You can use the The example screenshot project. It already follows most of the rules stated below. There has been no automatic screenshot tool since TYPO3 v11 as it proved to be to complicated to maintain.
t3docs/site-package .typo3 or
t3docs.We have a ready to use TYPO3 project that you can run in GitHub Codespaces or locally on DDEV to make screenshots:
You will often see a screenshot where additional graphic elements have been added in the documentation. These additional graphic elements may be boxes, numbers or arrows.
If you want to add a translation to official documentation or to your extension documentation, please keep in mind that it must be updated and maintained long term.
Important
Before adding a translation to an official manual contact the Documentation Team.
In general, it is a good idea to keep the structure of the original language. That way, it is possible to switch the language on each page and wind up on the corresponding translated page.
Create a localization directory
for example Documentation/, Documentation/.
This directory contains a complete documentation project. So, you can effectively
copy the original Documentation directory.
Documentation
└── Localization.de_DE
├── Index.rst
└── Settings.cfgCheck the rendering
Render the documentation locally with Docker
The result will be in /Documentation-,
for example /Documentation-
Once the documentation has been rerendered on the documentation server, you can switch the language using the version selector.
Old manuals that are maintained by the TYPO3 Documentation Team usually are published under the Open Publication License. We keep that until something else may be decided somewhere in the future.
New manuals should be licensed under Creative Commons BY 4.0.
Contributing to the TYPO3 Documentation is much appreciated, and should be a rewarding and positive experience both for contributors and maintainers of the documentation.
With this document, we try to set up conventions and best practices. We welcome constructive feedback to this living document with suggestions to continuously improve our process.
As outlined in the chapter Contribute to the TYPO3 documentation, contributors can provide so called "Pull Requests" (PRs) to our manual repositories on GitHub.
When a Pull Request is made, we kindly ask contributors to note the following:
main branch. If the
changes you propose apply to specific versions of the documentation,
you can add a line like Releases: main, 12.4, 11.5 to note any
Git branch that your change would apply to. If you are unsure,
our maintainers will take care of it - this is just a step to make
their work easier.If you are interested in the work of our maintainers, read on in the next section.
This section is intended for current maintainers, but please read on, if you are interested in maybe becoming one in the future.
Contributions are very valuable: Anyone putting in the effort and time to help us should feel rewarded by doing so. We try to adjust our review policy to making this possible without sacrificing the quality of our documentation.
The review process should have the same standard for anyone of the maintainer team performing the review, and every member of the team should feel good when making decisions on what and how to give feedback on.
.github action code changes or general
code snippets)A maintainer can and should always directly edit/commit a Pull Request to apply the following changes without the need to first ask for feedback of the contributor or other team members:
The following more specific checks to be fulfilled, before a Pull Request can be merged:
Backport 12.4
or Needs language rework or Needs CodeSnippet so that possible follow-up
Pull Requests can be created.#documentation-team ). Negative public feedback can be off-putting and must only
be raised after internal discussion, because this can reflect back to
the TYPO3 project as a whole. Be encouraging in your feedback to give
the contributor a chance to improve or agree to errors or wrong
direction.After a Pull Request has been merged:
Some decisions can not be made objectively, there may be reasons against and for it. Like picking "spaces or tabs" for intendation, or how to apply Uppercase Wording.
Here is a list of currently agreed stances:
makeInstance calls,
whenever possible.A few things still need to be addressed:
Unify the GitHub labels for all TYPO3-Documentation projects to have:
Create a list of "opinionated" and problematic decisions, aligned with the best practices of the TYPO3 Core Team. For example:
Most of the time changes will be made to branch main and backported.
When creating a pull request, it is possible to add a Releases line in the
commit message (as done in the Core):
Releases: main, 12.4However, this is not enforced and not always done. In any case, it is up to the user merging a PR to decide how far the changes are to be backported.
Here are some tips and conventions:
Apply your changes to the latest version you have verified your change to work with. If it is possible, apply your change to the "main" branch.
Leave a hint about which versions you have tested, for example:
Verified this on 12.4 and 11.5, I suspect it will also still be the case on
main. Could someone verify this please?
Releases: main, 12.4, 11.5The backporting itself will be done by the maintainers of the Documentation Team. Sometimes automatic backporting is not possible due to changes in the documentation structure. In such a case, you may be asked, if you would like to provide a pull request for the back versions.
Note
Only bugs will be backported more then one version. Improvements, etc may only be backported to the latest LTS release.
When the pull request needs to be backported, add labels for all needed versions to the pull request.
Example: If the pull request needs to be backported to version 12.4 and 11.5, add the corresponding labels backport 12.4 and backport 11.5. The labels will trigger an automatic backport once the current pull request is merged or the label is added to an already merged pull request.
The CI runner will create a separate pull request for each version that has been labeled - if, and only if, it can do the cherry-picking into the branch without conflicts.
If the automatic backport is successful, a new pull request will be created for the backport. This pull request can be approved and merged manually.
If the backport fails, a comment will be added to the original pull request. The label backport failed will be added to the original pull request and manual cherry-picking is required.
Convention: We backport to the newest LTS version unless the changes only apply to the main version. Major errors and bug may be backported to the older LTS version.
There may be reasons to do this differently:
Using the second option in the green Merge pull request button Squash and merge has proven useful for a number of reasons:
If there are more than one contributor who committed changes, a text about additional authors is automatically added to the commit.
Please make sure that you are in the branch you have just pushed into.
Preferably main:
git checkout mainLook up the commit ID with
git logSwitch to the branch to which you would like to make a backport.
If you cherry-pick a commit locally, you can (optionally) use
-x to
automatically insert information that this is a cherry-pick and
the original commit ID.
This makes the history clearer.
git cherry-pick -x <commit-id>This is how the commit might look like:
Author: Author <email@example.org>
Date: Fri Jun 26 15:50:08 2023 +0200
[TASK] Subject
(cherry picked from commit 609493dd8893cbac7ad78aa38a23e02d011bb0c2)If a merge conflict arises solve the merge conflict within the Git related
files like rst and md.
For a visual confirmation you can now execute the building process again with:
make docsIf everything looks fine continue the cherry-pick with
git cherry-pick --continuePush your changes. Check in the intercept to see if a new rendering has started. Once this is done, check the documentation to see if the backport worked as expected.
Whenever a change to the TYPO3 Core potentially affects the users a changelog entry is created or edited, for example:
Deprecated since version 12.3
The hook shown here is deprecated since TYPO3 12.3, use the event XYZ instead.
Each Core change affecting the changelog automatically creates an Issue in the repository Changelog-To-Doc. New issues here should be treated with priority.
All changes that are related to such an issue should contain a reference in their commit message to the issue, for example
[FEATURE] Add ApplicationContext to TypoScript data
Resolves: https://github.com/TYPO3-Documentation/Changelog-To-Doc/issues/790
Releases: mainAll information about deprecations should be marked with the
.. deprecated::
directive and the version of deprecation.
Deprecated since version 12.3
The hook shown here is deprecated since TYPO3 12.3, use the event XYZ instead.
.. deprecated:: 12.3
The hook shown here is deprecated since TYPO3 12.3, use the event XYZ
instead.In the ideal workflow a deprecation option will be removed with a breaking change in the next major version. We can then just remove the deprecated section.
Using the correct directive will help the documentation team to find and remove deprecation hints in later versions.
Ideally a breaking change was prepared by a deprecation in the previous version. In this case we can just remove the deprecated section.
When important concepts changed that might confuse the users we sometimes leave
a
.. versionchanged:: directive to inform users where to head now.
Changed in version 11.5
The widely used
->execute method has been split into:
php:->execute and
->execute. Read more.
.. versionchanged:: 11.5
The widely used :php:`->execute()` method has been split into:
php:`->executeQuery()` and :php:`->executeStatement()`. Read more.For emphasis you can also put the version changed directive into a warning or info box:
Warning
Changed in version 11.5
The widely used
->execute method has been split into:
php:->execute and
->execute. Read more.
.. warning::
.. versionchanged:: 11.5
The widely used :php:`->execute()` method has been split into:
php:`->executeQuery()` and :php:`->executeStatement()`. Read more.Using the correct directive will help us to track down and remove these hints in later versions.
When adding a new feature to the docs that is not yet availible in all supported
TYPO3 versions, it can be helpful to mark it with the
.. versionadded::
directive:
New in version 13.0
A PHP attribute
\TYPO3\ is
available to autoconfigure a class as an event listener...
This directive not only highlights new features but also assists users who are reading the manual in a version that does not align with their installation, ensuring clarity in cases where feature compatibility may differ.
The documentation team removes these directives when the feature is present in all supported TYPO3 versions.
To regenerate the existing code snippets in a manual or extension clone the repository of that manual.
git clone git@github.com:TYPO3-Documentation/TYPO3CMS-Reference-CoreApi.gitUse composer to install all dependencies, including dev-dependencies. In official manuals we have a make command for your convenience.
make install# in repositories with composer.lock in version control
composer install
# in repositories where the composer.lock is not in version control
# to prevent outdated packages due to a local composer.lock from earlier install-runs
composer updateThen regenerate the code snippets. Official manuals should have a make command for that.
make codesnippets# Paths depends on where the vendor binaries are installed
# And where the configuration file codesnippets.php is located
vendor/bin/typo3 codesnippet:create Documentation/The Fluid ViewHelper Reference gets automatically updated by changes to the according ViewHelper classes in the TYPO3 Core and the package Fluid Rendering Engine.
The generated documentation specifically depends on the phpDoc-style inline
comments on top of the ViewHelper classes as well as the configured arguments in their
php:initialize method.
Changes in wording or arguments thus need to be made inside the relevant files of these two repositories. For contributions to the TYPO3 Core, follow the TYPO3 Contribution Guide - Core Development.
The Fluid View
is responsible for creating both a directory structure of rst files and
a json file for each documented Fluid namespace. The Fluid namespaces to be documented are configured
in JSON files in this repository, which also support combining multiple namespaces into one
(because f:* in TYPO3 combines both EXT: and Fluid Standalone ViewHelpers).
The rst files generated in step
Generation of the reStructuredText files and JSON files will be saved by the
GitHub action into
the repository Fluid View.
In this repository all files not overridden by the
Fluid View
are maintained, Including the start page Index. and the
guides.xml. This repository is then rendered by
the standard rendering process.
All processes described above are combined for automatic execution as a GitHub action in the repository t3docs-ci-deploy. It is triggered automatically once a day, or can be executed manually through the GitHub UI by the TYPO3 Documentation team.
Maintainers needs to occasionally watch for failed or stuck Workflow runs.
Note
This document is not complete and will be updated with the release of TYPO3 v14.0.
The section describes the doings when a new major Core version is released (like version 14.0).
Update
to reflect the new version upon installation/upgrade.
Add "-dev" links (like 14-) to the links on the homepage:
The landing page of https://api.typo3.org/ is automatically updated when this file is updated in GitHub:
As this is a pure HTML file, we currently keep the content in this rst file:
https://github.com/TYPO3-Documentation/DocsTypo3Org-Homepage/blob/main/Documentation/Home/ApiTypo3Org.rst
locally render it,
then update Web with the
rendered output.
The workflow responsible for replacing the landing page is https://github.com/TYPO3-Documentation/DocsTypo3Org-Homepage/blob/main/.github/workflows/apihome.yml
The content per version https://api.typo3.org/main, https://api.typo3.org/12.4 etc is generated with phpDocumentor. The theme is defined in this repository: https://github.com/TYPO3-Documentation/render-guides/tree/main/packages/typo3-api
The rendering is triggered by this workflow which we in the documentation team can change: https://github.com/TYPO3-Documentation/t3docs-ci-deploy/blob/main/.github/workflows/api-typo3-org.yml
Attention
This workflow is running automatically for max 60 days then it has to be restarted manually
Using your local machine instead of editing documentation on GitHub has many advantages, it includes the freedom to choose which IDE you make your changes in and it also gives you the ability to experiment and preview your changes locally before submitting them for approval.
Create a GitHub account:
Visit Join GitHub and create your account.
Though not mandatory, the general convention in the TYPO3 community is to set your GitHub name (not username) as your full name.
Find and fork the repository
In the footer of the documentation you wish to make changes to, select the Repository link.
This will take you to the documentations repository in GitHub.
From here, select the "Fork" button in the upper right corner of the page.
Clone the forked repository
Clone the forked repository from your workspace (select Clone or download to copy the URL).
In your terminal:
git clone https://github.com/<USERNAME>/<NAME OF REPOSITORY>.gitSetup Git Settings and SSH Key
For this, we refer to the general help on Git and GitHub:
Setup username
and email
(if not already setup in your global ~/.).
Create a branch for your changes
Important
If you did not just fork and clone but are instead using an old local version of this repository:
Always branch from main.
If you are checked in to a feature branch, switch back to main
first:
git checkout mainFor example, create the branch feature/:
git checkout -b feature/changes-in-cglMake your changes
Using your preferred IDE or editor you can now start making your changes.
If you are not familiar with reST, you can visit the reST Introduction to help get you started along with the ReST Cheat sheet: Using reStructuredText in TYPO3 Documentation.
Render the documentation
Render your changes with Docker to preview them locally:
Commit
git commit -aWrite a short, meaningful commit message describing what changes you have made.
Push changes
git push origin changes-in-cglThis will push the change to your forked repository.
Create Pull request
Now, in your browser, visit the forked repository in your GitHub workspace. GitHub will already make some suggestions for a pull request and will display your pushed branch as "Your recently pushed branches".
Click on the green button "Compare & pull request" and then "Create pull request".
Your change will now be reviewed. A reviewer might suggest additional changes. Monitor your notifications (email) from GitHub. If at any point, you are not sure what to do, don't hesitate to ask for help. When your pull request is accepted, it will be merged. You will receive a notification email as soon as this happens.
More information on how your submissions ("PR"s, "Pull Requests") will receive feedback can be found in the chapter Policy for making and reviewing contributions.
Congratulations! You are now a contributor. Welcome and thank you!
This section describes how to keep your local repository up-to-date. This is similar to the GitHub documentation in chapter Keep your fork synced.
If you have already created a patch for a repository, you can reuse your local repository. This means you do not have to fork and clone for every new patch.
However, if you reuse your local clone, you should make sure it is up-to-date before you create another branch for a new patch.
You local repository is based on the forked repository in your workspace.
For example,
git@github.com:<your username>/TYPO3CMS-Guide-HowToDocument.git git@github.com:TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument.git So, running the following will not get the latest changes:
git pull origin mainbecause origin points to your fork.
You must now do the following:
git remote add upstream git@github.com:TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument.git
git pull upstream mainReplace the URI with the correct URI for the original repository, not your fork!
The URL for upstream has now been written to .git/ in your local repository,
so next time it is enough to do:
git pull upstream mainNow, continue with step 5 (create branch) in the first section of this page.
For more information in this guide:
For more information about GitHub see the help pages on GitHub or other resources, for example:
Create a GitHub account:
Visit Join GitHub and create your account.
Though not mandatory, the general convention in the TYPO3 community is to set your GitHub name (not username) as your full name.
Find a page that needs improving:
For example, you may have found a misspelling in the TYPO3 - Getting Started Tutorial or you want to add some new content to the Upgrading the TYPO3 Core and extensions.
Edit the page on GitHub:
At the top right of every page you will find an icon that says "Edit me on Github". Selecting this link will take you to that pages repository on GitHub.
Fork the repository:
Click on the green button to fork the repository. This will clone the repository into your GitHub account, ready for you to make your changes in your browser.
Make your changes:
You will be presented with a window where you can make your changes. The "Indent mode: Spaces" and "Indent size: 4" values should already be set - do not alter these.
Working with reST files:
Every page you edit is written in reST format, when it comes to making minor amendments no prior knowledge of editing .rst files is required. However, when you are ready to make more advanced changes, you can learn more about working with reST here.
Preview your changes:
Select "Preview changes" to see what your changes will look like once they are published.
You can go back and make further changes at any time, select the Edit file tab to continue editing.
Finalize your changes:
When you are ready, scroll down to the bottom of the page. Add a short (but meaningful) description that outlines the changes you have made and click "Propose file change"
Create pull request:
GitHub will show you an overview of your changes. If you are happy with them, select "Create pull request".
Finally, create your pull request:
You're done!
Your change will now be reviewed. A reviewer might suggest additional changes. Monitor your notifications (email) from GitHub. If at any point, you are not sure what to do, don't hesitate to ask for help. When your pull request is accepted, it will be merged. You will receive a notification email as soon as this happens.
Congratulations! You are now a contributor. Welcome and thank you!
After a short period your changes will be automatically rendered, reload the page and your changes will be visible to everyone.
Next month, your name will be listed in the "Developer Appreciation Day" (DAD) page on the TYPO3 Blog.
See June 2018: Developer Appreciation Day for an example.
Scroll down to "Improving documentation":
Everyone is welcome to make changes and help improve TYPO3's documentation.
No prior knowledge is required and support is always available for new contributors here.
Once you have submitted your changes they won't be visible straight away. Someone in the Documentation Team will need to approve the changes first before they are published.
More information on how your submissions ("PR"s, "Pull Requests") will receive feedback can be found in the chapter Policy for making and reviewing contributions.
Workflows
There are two different ways in which you can make your changes before submitting them for approval.
Edit on GitHub
You can edit documentation in your browser by accessing its repository directly on GitHub.
This workflow is ideal for making minor changes such as fixing grammatical errors and typos.
Edit locally and render with Docker
This method is suited to users who are comfortable using Git, Docker and the command line. It's the recommended approach for making larger changes as it gives you greater control over what tools you use and it also allows you to test and view your changes locally before submitting them for approval.
Everyone can contribute to the TYPO3 documentation and contributions are very much appreciated.
Note
These are just examples to get you started. As a contributor, you are not restricted to this. If you can make useful improvements, do it! Some of the best contributions come from starting with something that bothers you the most.
If you see a typo, a broken link, something is outdated or you can make improvements in any way, do not hesitate to click on Edit on GitHub button and make the change yourself. See Workflow #1: "Edit on GitHub" for a walkthrough.
Pick an issue for a topic you are familiar with and try to fix it. Some of the issues address a problem, some are enhancements where new text needs to be written.
You can look at the open issues of a manual you are familiar with, pick one and fix the problem.
For example:
Here are some links to GitHub issues in TYPO3-Documentation.
Important
GitHub will show a 404 page if you are not logged in following these links! So, remember to log in first!
For new contributors:
For contributors:
For team members and advanced contributors:
The Docker image for rendering is in the organization t3docs (instead of TYPO3-Documentation):
Some pull requests make changes in documentation describing an aspect of TYPO3 you may know well. Help in this area is very much appreciated!
Important
GitHub will show a 404 page if you are not logged in following these links! So, remember to log in first!
Anyone is welcome to review open pull requests!
In TYPO3-Documentation:
In t3docs (Docker image):
Often things can be conveyed more easily if visual aids like diagrams are used in conjunction with text.
You can create UML diagrams such as class diagrams, sequence diagrams and cheat sheets.
Here are some examples:
Check out sequence diagram on new page about request handling
Example of a sequence diagram about request handling
Look at Using images in ReST documentation for information about how to embed images with reST.
Add some new YouTube videos from the TYPO3 YouTube channel.
See Embed YouTube videos for information on how to do this.
Pick a manual and start reviewing it. If you find something that needs fixing or something is missing, either fix it or write an issue for it, if you cannot make the changes yourself.
Tip
Usually, there is one branch for each major TYPO3 version in a manual. Please focus your efforts mostly on the "main" branch, to get that up to date and ready! The Documentation Team will then check, if a backport to older versions makes sense.
Tip
If you do not have write access to a GitHub repository (which is usually the case if you just started), you cannot check off the checkmarks in the review list. In that case, just leave a comment in the issue.
Once you start and are confident that you can make progress, you may want to talk about your intentions in the #typo3-documentation Slack channel (as this is a bigger change). You can also mention, if you need help (because reviewing an entire manual can be quite too much to do for one person).
Note
Instead of reviewing and changing all pages of a chapter in one pull request, consider to split them into multiple pull request, for example, one per page. This makes the reviewing for the Documentation Team easier and you get feedback more quickly.
If you are already familiar with the workflow, you can help others to get started. Whenever you are at a TYPO3 event (sprint, barcamp, etc.), on StackOverflow or in a Slack channel and someone finds something missing or a problem in the documentation, help them make the necessary changes themselves.
Thank others for their contributions (for example on Slack, Mastodon or personally).
Tell others about things in the documentation, that are new, that you found interesting or that helped you in any way.
Remind people, that everyone can contribute!
Write on Mastodon (hashtag: #TYPO3). Additionally, you can use #T3Docs,
#T3Contribute, and mention @documentation@typo3.social.
Telling a real life story may help others to make the decision to contribute. It's your story, so you decide what is in it, but here are some ideas to get you started:
Sometimes you can directly add content in a manual or create an issue for it.
But, what if you are not sure, where the new content should go or if it should be created at all?
If this is the case, raise the question in the #typo3-documentation channel on Slack.
Each new or changed changelog from the TYPO3 Core creates an issue in the Changelog-to-doc repository. The issues are mostly already tagged with the according manual which has to be changed. If you want to pick up an issue, check if there is already a person assigned. If not leave a comment in the issue that you are working on it. This prevents two people working on the same issue.
Regardless of this, if you find something missing, you can add it yourself. Or ask in the #typo3-documentation Slack channel, if you can help out.
Check spelling for consistency. For example, compare spelling of title and headlines to the rules outlined in the Spelling chapter.
Do you have more ideas to add to this list? Either add them directly to this page using one of the two workflows or contact us in the #typo3-documentation channel on Slack.
Note
Since November 2024 the official documentation rendering process has been switched to a PHP-based rendering. When your documentation was configured with Sphinx, the rendering process will be automatically switched to the PHP-based rendering. The automatic migration will work for most cases, but some manual adjustments might be necessary. This guide will help you to migrate your documentation to the new rendering process.
The main difference compared to the Sphinx rendering is that the PHP-based rendering
requires a file called Documentation/ for configuration.
The Sphinx rendering required a file called Documentation/.
In the transition period the GitHub action of the official rendering process detects if a file called
Documentation/ is present and then automatically switches to the
PHP-based rendering.
Documentation/guides.xml The Docker container for the PHP-based rendering additionally consists out of
a migration tool. This tool can be used to automatically create a
Documentation/ based on the information contained in your
Documentation/.
Docker (or a drop-in replacement like Podman) needs to be installed on your operating system for the tool to work:
docker run --rm --pull always \
-v $(pwd):/project \
-it ghcr.io/typo3-documentation/render-guides:latest \
migrate Documentationpodman run --rm --pull always \
-v $(pwd):/project \
-it ghcr.io/typo3-documentation/render-guides:latest \
migrate DocumentationThe last parameter (
Documentation) is the name of the directory, where your
Settings. is currently placed in.
After the migration is performed, you will see some output in the terminal about which settings were converted, if some old settings were discarded, or errors occurred. When you see this:
Note: Some of your settings could not be converted:
* html_theme_options
* project_discussions
* use_opensearcheverything went well. They can be ignored since these files are usually files that
not need to be converted. You can now delete Settings.. If you ever should need it again it is still in the Git history. Also delete
file genindex. in your Documentation/ directory (if available).
While you could already jump in and render your documentation directly (see local rendering), we suggest to clean up the following other things first (see).
You should perform the following tasks to conclude the migration to the PHP-based rendering tool:
Manual modifications of the guides.
You have to manually change the following: in the
<extension> tag add the attribute
Changes in yourguides.xml interlink-shortcode="my-vendor/my-extension"Copied!
You can find the package name in your composer. file under "name".
For example, my-.
We recommend to reformat the code, for example in PhpStorm, using the Mac shortcut
cmd (⌘) + option/alt (⌥) + L, or Ctrl + Alt + L
on Windows/Linux and to use for every attribute one line.
Improve your documentation to render without warning
Rendering your documentation should not yield any warnings or errors.
If you get error messages, often they refer to wrong indentation, missing interlinks, orphaned files or outdated ReST identifiers.
If you are unable to address a warning/error with changes in your documentation feel free to ask in Slack channel #typo3-documentation (see Help and support).
If you believe you found a specific bug in the PHP-based rendering, please open an issue on GitHub.
Remove outdated files
After the guides. file has been created, you can remove the old
Settings. file.
You can also delete the genindex. file which was previously used
to generate an index.
Adapt Includes.
The main documentation directory can contain a file Includes.
to include any fixed text, which will be placed on every page of your rendered
documentation.
Previously, it was also used to define a list of utilized directives/roles.
You can either remove that file, or add your fixed text to it. If you remove the file, remember to also remove all references pointing to that file, like:
.. include:: /Includes.rst.txtMost official documentation uses this as the stub of the file:
.. You can put central messages to display on all pages hereRemove the entry genindex from Index. (Index/Glossary)
If you previously had a genindex. file, this optional index
(or glossary) was rendered as a page through an entry in the file Index.
like this:
.. toctree::
:hidden:
Sitemap
- genindexRemove the entry genindex from the list.
Hint
See To be discussed: Index generation (glossary) for details about the future of the index (glossary) generation.
Avoid code snippets with .rst extension
All files with the extension .rst will be interpreted by the PHP-based
rendering, and every file that is just a code snippet placed in an external file
should be renamed to use a .rst. extension instead.
Use our Docker container to render your documentation locally. Read more about it in local rendering.
The following list is not a requirement to utilize the PHP-based rendering, but
follows "best practice" to make the most of your documentation project.
One of the biggest benefits is, that this simplifies finding
errors in your reST syntax.
The Makefile helps you to launch the local rendering described in here.
You create the Makefile in order to register the command shortcuts that you
would use to render your documentation locally and also provide an entry point for further shortcuts (like testing).
Makefile to your project A Makefile is a simple command line runner configuration file, which requires
the utility GNU make
to be available on your Unix-based operating system (Linux, macOS, WSL on Windows,
for example).
This allows you to render your documentation by using
make docsinstead of typing a long
docker run... or
podman run... command.
When rendering locally you should ideally see something like this
Successfully placed 7 rendered HTML, SINGLEPAGE, and INTERLINK files into /project/Documentation-GENERATED-tempmake docs We provide four example errors to guide you through the fixes.
[2024-03-13T12:22:50.661532+00:00] app.WARNING: Interlink inventory not found: HTTP/2 404
returned for "https://docs.typo3.org/m/typo3/book-extbasefluid/11.5/en-us/objects.inv.json". [] []Here you see that the link https:// is not found (404 page).
We can now check via Google if there is another link to book Extbasefluid. We found this site https://
We can find the hint: This manual is no longer being maintained for TYPO3 versions 11.. This tells us that the Documentation Team abandoned this
manual. We can, for example, link to the last existing version. Which is 10.4. To do this we have to change the guides.. Search for the
<inventory id="t3extbasebook"
url="https://docs.typo3.org/m/typo3/book-extbasefluid/11.5/en-us/"
/>and change 11. to 10.. Generate files again. Keep in mind, that this is a
workaround to avoid warnings temporarily. References to outdated manuals should be adjusted
as soon as possible.
[2024-03-13T12:26:40.940930+00:00] app.WARNING: Inventory link with key "rest-common-pitfalls"
(rest-common-pitfalls) not found. {"rst-file":"GeneratedExtension/Index","type":"ref","targetRefWe see already that we have to go to file Generated in the directory "Documentation".
In there we have to delete the line which contains
* :ref:`rest-common-pitfalls`But whether we should delete the reference or not depends on the special case. In this case the whole section was removed. So here it is useful to delete the reference. We conclude: In general it depends on the case itself what the best solution is.
[2024-03-25T13:26:11.600367+00:00] app.WARNING: Nested PHP domain components
(php:class, php:interface, php:enum etc) are not supported.
Found php:\Vendor\MyExtension\Interfaces\RequireJsModuleInterface inside
\Vendor\MyExtension\Interfaces\AnotherImportantInterface {"rst-file":"Developer/Index.rst"} []The file Index. in Documentation/ has a wrong indentation. A class must not belong to another class.
Here is the wrong rst code.
.. php:class:: AnotherImportantInterface
Used for ...
.. php:class:: RequireJsModuleInterface
Widgets implementing this interface will add the provided RequireJS modules.
Those modules will be loaded in dashboard view if the widget is added at least once.Additionally regarding the name it has to be interfaces and not classes.
.. php: has to be changed to
.. php:.
The next step is to visit the site which was rendered with the Sphinx rendering, in our example
https://.
There we can search for sitehandling- in the restructured text code by clicking the button "</> View Source".
We have found this:
.. tip::
For more information on how to add languages and configure their
behaviour in the site configuration, see
:ref:`Adding Languages <sitehandling-addinglanguages>`.The link is leading to
https://.
We have to click the symbol next to the heading and copy the correct link
which is the one for restructured text
:ref:`Adding Languages <t3coreapi:sitehandling-addingLanguages>`You have to replace the correct link in, for example, Documentation/ to
fix the error. Note: Since we already migrated the Frontend Localization Guide
(https://)
to use the PHP-based rendering you cannot find the state that we have shown above anymore.
For inspiration, check out the Makefile of the main PHP-based rendering
repository:
https://github.com/TYPO3-Documentation/render-guides/blob/main/Makefile
A small example Makefile:
.PHONY: help
help: ## Displays this list of targets with descriptions
@echo "The following commands are available:\n"
@grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[32m%-30s\033[0m %s\n", $$1, $$2}'
.PHONY: docs
docs: ## Generate projects docs (from "Documentation" directory)
mkdir -p Documentation-GENERATED-temp
docker run --rm --pull always -v "$(shell pwd)":/project -t ghcr.io/typo3-documentation/render-guides:latest --config=Documentation
.PHONY: test-docs
test-docs: ## Test the documentation rendering
mkdir -p Documentation-GENERATED-temp
docker run --rm --pull always -v "$(shell pwd)":/project -t ghcr.io/typo3-documentation/render-guides:latest --config=Documentation --no-progress --minimal-test
Hint
Makefile blocks need to be indented with a TAB character, not spaces. If your project comes with an .editorconfig definition for code formatting, you should add the following:
[Makefile]
# Use tabs for indentation (Makefiles require tabs)
indent_style = tabIt is recommended to use an automatic workflow on GitHub Or GitLab to ensure the extension's documentation renders without warnings.
An example workflow on GitHub would be established via this file in
.github/:
name: Test documentation
on: [ push, pull_request ]
jobs:
tests:
name: Render documentation
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Test if the documentation will render without warnings
run: |
mkdir -p Documentation-GENERATED-temp \
&& docker run --rm --pull always -v $(pwd):/project \
ghcr.io/typo3-documentation/render-guides:latest --config=Documentation --no-progress --minimal-test
This creates a workflow entry Test documentation, so that on every push to your
repository, and every pull request, the rendering is executed. A commit will then
not be possible, if the rendering fails. The workflow run will be marked with an error,
and shown on pull requests.
The Sphinx rendering allowed to utilize a syntax like the following to add indexes to your documentation:
.. index::
XLIFF; Files
File; XLIFFThe automatically generated file genindex. would show a
two-column layout of all indexes, with the pages that they were used on.
The PHP-based rendering does not (yet) support this indexing.
The current recommendation is to only remove the genindex. file
from your documentation directory, but keep all the placed .. index
directives. If at some point the automatic index generation is re-introduced,
your old indexes will be able to show up again.
Markdown is very popular and widely used for documentation. However, ReST is more powerful and flexible. The TYPO3 documentation toolchain contains a lot of features that are only available with ReST. Because of the extendability of ReST. This guide explains how to migrate Markdown files to ReST, using the TYPO3 documentation toolchain.
Unless you have a specific reason to migrate to ReST, it is perfectly fine to keep using Markdown. The TYPO3 documentation toolchain supports both formats.
Note
This guide assumes you have already set up the TYPO3 documentation toolchain. If you haven't, please follow the instructions in the Render documentation with the TYPO3 theme guide.
The first step is to convert the Markdown files to ReST. This can be done using
our rendering toolchain. This will convert the Markdown files to ReST format.
We will use Documentation-Migrated as the output directory.
mkdir -p Documentation-Migrated
docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --theme=rst --output-format=rst --output Documentation-Migratedmkdir -p Documentation-Migrated
docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --theme=rst --output-format=rst --output Documentation-MigratedNew-Item -ItemType Directory -Force -Path ".\Documentation-Migrated"
docker run --rm --pull always -v ${PWD}:/project -it ghcr.io/typo3-documentation/render-guides:latest --theme=rst --output-format=rst --output Documentation-MigratedNow we can copy the guides.xml from the original directory documentation directory to the new directory. And remove the
option input-format="md". This will tell the rendering toolchain to use the ReST files instead of the Markdown files.
Last step is to swap the directories. Rename the original directory to Documentation-Markdown and the new directory Documentation-Migrated to Documentation.
The basic migration is now done. Some manual adjustments might be necessary, as the conversion is not perfect.
Tip
If you notice any issues with the conversion, please report them to the TYPO3 documentation team.
You can render documentation by executing the following command in the folder
that contains the Documentation folder:
docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --config=DocumentationOpen the file saved to Documentation- in a
browser of your choice.
The official manuals commonly contain a make file. You can use the short command:
make docsDocumentation folder locally with Docker You can render the documentation of an official TYPO3 manual or a third-party manual with the following steps:
composer.json .Check if there is documentation to be rendered:
A folder called Documentation containing at least the files
Index. and guides..
Make sure that Docker is installed on your system.
Tip
Did you know: Instead of the
docker client you can also use
the lightweight drop-in replacement Podman to run
the mentioned containers by replacing all
docker commands in the
following steps with
podman.
docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --config=DocumentationOpen the file saved to Documentation- in a
browser of your choice.
For your documentation to be published to https://docs.typo3.org, your
TYPO3 extension has to have a valid composer. and either a folder
called Documentation with a Documentation/ and
a Documentation/ or a README. / README.
in the extension's root directory.
The extension has to be publicly available on GitHub or GitLab. You have to establish a Webhook and the Documentation Team has to approve your first rendering.
It is recommended to make sure your documentation always renders without warning. On GitHub or GitLab you can introduce actions that test your documentation automatically:
name: test documentation
on: [ push, pull_request ]
jobs:
tests:
name: documentation
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Test if the documentation will render without warnings
run: |
mkdir -p Documentation-GENERATED-temp \
&& docker run --rm --pull always -v $(pwd):/project \
ghcr.io/typo3-documentation/render-guides:latest --config=Documentation --no-progress --minimal-teststages:
- test
test_documentation:
stage: test
image:
name: ghcr.io/typo3-documentation/render-guides:latest
entrypoint: [""]
script:
- mkdir -p Documentation-GENERATED-temp
- /opt/guides/entrypoint.sh --config=Documentation --no-progress --minimal-testYou want to write complex re markup and directly see the
rendered output, browser side-by-side with your editor? Then
this section is for you!
Often, especially in the later stages of creating documentation, you just edit small parts of the reST files, render the outcome manually and happily commit your changes.
However, in cases you write larger sections of text, you may want to get more immediate visual feedback on your changes, but do not want to manually trigger the rendering time and again.
To make this easier, render- can serve the rendered documentation
via a local web-server and automatically re-render the documentation
when changes in the source files are detected. This gives you a more
WYSIWYG-like experience when writing documentation.
This allows you to have a browser window next to your reST file editor to view progress.
docker run --rm -it --pull always \
-v "./Documentation:/project/Documentation" \
-v "./Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp" \
-p 1337:1337 ghcr.io/typo3-documentation/render-guides:latest --config="Documentation" --watch
xdg-open "http://localhost:1337/Index.html"docker run --rm -it --pull always \
-v "./Documentation:/project/Documentation" \
-v "./Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp" \
-p 1337:1337 ghcr.io/typo3-documentation/render-guides:latest --config="Documentation" --watch
xdg-open "http://localhost:1337/Index.html"docker run --rm -it --pull always \
-v "./Documentation:/project/Documentation" \
-v "./Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp" \
-p 1337:1337 ghcr.io/typo3-documentation/render-guides:latest --config="Documentation" --watch
xdg-open "http://localhost:1337/Index.html"The command above can also be added to your project's Makefile or
you can create a bash alias like:
alias render-wysiwyg="docker run --rm -it --pull always \
-v './Documentation:/project/Documentation' \
-v './Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp' \
-p 1337:1337 ghcr.io/typo3-documentation/render-guides:latest --watch"Note
If anything on your host operating system already utilizes the TCP port
1337 you need to adapt that command to use another free TCP port for you,
and adapt the port in the web-browser URL.
You can do this by changing the
-p parameter, e.g. to
-p 8080: to use TCP port 8080 on your host system.
If you are using docker-compose to manage your development environment, you can add a service for the live rendering like this:
services:
render-wysiwyg:
restart: "no"
image: ghcr.io/typo3-documentation/render-guides:latest
ports:
- "1337:1337"
volumes:
- ./Documentation:/project/Documentation
- ./Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp
command: ["--config=Documentation", "--watch"]Note
Render guides was never optimized for long running services. You might need to restart the container from time to time to free up resources.
For integration with DDEV projects, a DDEV addon has been created at https://github.com/TYPO3-Documentation/ddev-typo3-docs.
This can be used to automatically start the live documentation preview within the DDEV project at http://<yourproject>.ddev.site:1337/
whenever you start that project, and can directly view and work on documentation alongside the project.
In this environment, users do not even need to execute a manual docker run command anymore, and have full integration at hand.
Not all changes in the source files can be detected automatically, or will impact the rendered output immediately. In such cases, a manual re-rendering is required. Examples are:
guides.xml Note
Please be aware that some editors (like e.g. VIM) create temporary files
when opening files for editing. This will not be detected as a change to the
actual file and thus not trigger a re-rendering.
This chapter explains how to write documentation for a new extension.
This guide uses the example extension manual as a template for starting out.
Use the following Docker command to render your documentation guide locally:
docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --config=DocumentationOpen the file saved to Documentation- in a
browser of your choice.
The Rendering the Documentation folder locally with Docker has more information.
The following Docker command helps you to create some basic documentation
including the required configuration file Documentation/:
docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest initThe command creates a folder Documentation in the directory it is called
from. This should be the root directory of your extension containing the
composer.json.
Follow the interactive dialoge. We suggest to use the option ReStructuredText (rst) as this format provides the full power of the TYPO3 documentation theme. Using Markdown (md) is an option for simple and quick one page documentation.
If your extension offers a main Site set enter its name and path when prompted. This will regenerate ready to use documentation about configuration for you. If you have more then one set you can document the other sets manually. If you have no set, you need to write the chapter your self.
Make changes and try rendering the new documentation.
To publish your documentation to https://docs.typo3.org a webhook needs to be added on GitHub, Bitbucket or GitLab. A member of the Documentation Team has to approve your new documentation guide for publishing. In case the Team has questions, please follow the thread generated for your extension in the TYPO3 slack organization in channel #typo3-documentation.
docs.typo3.org does no longer show three level version numbers in form of Major.Minor.Patch.
Only the first two levels are shown Major.Minor.
This reduces the amount of documentation while keeping relevant information, as patch levels should not introduce breaking changes or new features.
The rendering supports two branches within repositories:
main / masterShould contain the current development state, used for upcoming release.
Every push to these branches triggers a new rendering, available at
https://.
Both branch names are supported, but result in the same URL.
Please use main, master is only supported for backward compatibility.
documentation-draftShould contain a draft of the documentation.
Every push to this branch triggers a new rendering, available at
https://
(same URL as main, except main is replaced by draft).
This is not indexed by search engines. This branch can be used to test rendering before releasing a new version of an extension.
In order to test a different rendering, remove the branch, and create it again.
This section explains how to configure webhooks for automatic documentation rendering in a repository.
TYPO3 documentation rendering supports Git as a Version Control System (VCS) and integrates with the following repository hosts:
Table of Contents
Before your documentation is rendered, the TYPO3 Documentation Team must approve the repository the first time you request rendering.
For approval, ensure the following:
These steps help prevent misuse of the infrastructure and ensure extension name consistency.
If the approval process takes too long, request approval via the Slack channel #typo3-documentation. Register for Slack at my.typo3.org.
If your repository is hosted outside the supported platforms (GitHub, GitLab, Bitbucket) or its structure differs from a typical TYPO3 extension, you must create a mirror on a supported platform. Otherwise, automatic rendering will not be possible.
If you are new to webhooks, refer to the GitHub Webhooks Guide.
The webhook setup described below ensures that rendering is triggered only on push events.
To test the webhook integration, push changes to
the main or documentation- branch (see Supported branches).
Note
Documentation rendering is triggered only for the version affected by the
push event, not the entire repository. For example, a push event on
branch 13. will render only that version.
If a webhook was previously configured, it may be using a deprecated method. A compatibility layer is still in place but will be removed in the future.
To enable automatic documentation rendering using GitHub webhooks, follow these steps:
Navigate to the repositories Settings tab.
Open the Webhooks section.
Click Add webhook.
Configure the webhook settings:
https://docs-hook.typo3.org application/json Just the push eventClick Add webhook.
Verify webhook creation.
GitHub will confirm that the webhook was successfully added.
Test the webhook.
Visit intercept.typo3.com
and check the Recent actions section. Push a commit
to main or documentation- to trigger the webhook.
To configure a webhook for a Bitbucket repository:
Open the repository Settings.
Go to the Webhooks section.
Click Add webhook.
Configure the webhook:
TYPO3 Docshttps://docs-hook.typo3.org Repository pushClick Save.
Verify webhook creation.
Bitbucket will confirm webhook addition.
Test the webhook.
Visit intercept.typo3.com
and check Recent actions. Push a commit
to main or documentation- to trigger the webhook.
To set up a GitLab webhook:
Open the Integrations section of the repository.
Add a webhook with the following settings:
https://docs-hook.typo3.org Push events and Tag push eventsClick Add webhook.
Verify webhook creation.
The webhook will appear in the list.
Test the webhook.
Visit intercept.typo3.com
and check Recent actions. Push a commit
to main or documentation- to trigger the webhook.
To test webhook configurations before integrating with TYPO3, use:
These tools help debug webhook calls and ensure correct configuration before enabling documentation rendering.
If there are documentations for some extension version missing, they have to be announced to Intercept again. This can be achieved by triggering the Webhook with the correct version number. Therefore please register webhook first, if it's not already done.
As no new releases should be created, branches can be created for each existing release. Those branches need to match the release version. The created branches can be pushed, to trigger the webhook. Once done, those branches can be removed again, to keep the repository clean.
With a lot of versions release this task can get very tedious. To get over it in an efficient way, the following script can help with the task:
#!/bin/sh
EXTENSION="$1"
mkdir -p "/tmp/$EXTENSION"
git clone "git@github.com:$EXTENSION.git" "/tmp/$EXTENSION"
cd "/tmp/$EXTENSION"
for tag in $(git tag)
do
git checkout -b $tag $tag;
git push origin refs/heads/$tag;
sleep 60;
git push --delete origin refs/heads/$tag;
git checkout main;
git branch -D $tag;
done
rm -rf "/tmp/$EXTENSION"The script needs to be called with the repository name.
If the script is saved with the name trigger_ this would be executed using this example:
sh trigger_documentation_push.sh evoWeb/sf_registerThis will:
All versions should now be queued for the extension. This can be checked as described at Webhook last step.
Short answer: it will take a few hours and up to a day until the documentation for new extensions is linked in the details of your extension in the TYPO3 Extension Repository (TER).
Long answer: the documentation of all extensions is exposed by an API which is consumed by the TER through a TYPO3 Scheduler task. The TER first needs to pick up updates of extensions which by itself can take some time due to server and browser caches. Furthermore the search in the TER also needs some time to update its index.
Finally the TER will only link to documentation with a matching version, so make sure that there actually is a documentation version for each of your extension version. See Reregister versions to publish documentation for already released versions.
If you are missing documentation for some extension versions we have a workaround to fix that.
Refer to Migration: From Sphinx to PHP-based rendering in order to fix this issue.
You must add the project title to your Settings.:
[general]
# .................................................................................
# ... (required) title (displayed in left sidebar (desktop) or top panel (mobile)
# .................................................................................
project = title, for example extension name
# .................................................................................
# ... (recommended) version, displayed next to title (desktop) and in <meta name="book-version"
# .................................................................................
release = 2.0.0Settings: Documentation/guides.xml provides detail information.
There are several possibilities:
How do you make sure only the author of the extension publishes the documentation?
Documentation rendering is restricted to one repository per package.
I.e. if someone triggers documentation rendering with a repository with vendor myVendor and
package myPackage, then nobody else will be able to trigger documentation from
a different repository with that exact vendor/ name combination. You
could say this works on a first come first served basis.
We have added mechanisms to prevent registering a package from the wrong repository
with malicious intent or accidentally: The first time someone triggers documentation
rendering for a specific vendor/ combination, the Documentation Team must
approve of this. This way, misuse is prevented.
See Webhook for more information.
Yes and no. Regular users do not have this option at the moment. However, as a member of the Documentation Team you can go to https://intercept.typo3.com and log in with your typo3.org account. Then in the menu you can navigate to Documentation > Deployments. At the top right hand side you will see a button Add Configuration. By clicking this button and going through the form, you can add a repository manually without the hook. Nevertheless we strongly recommend the usage of the webhook.
Yes.
The documentation and the extension at TER (https://extensions.typo3.org) are two separate, independent entities.
In theory you could have the documentation in GitHub (for example) and the extension (code) somewhere else (or not in Git at all). You just need to fire the webhook from GitHub/GitLab/Bitbucket to trigger the documentation rendering.
The documentation link should get updated automatically in TER.
Only use "external documentation" if your documentation is hosted somewhere else (not on docs.typo3.org).
GitHub (or Gitlab, bitbucket) etc. automatically render a README. (or .md)
on the repository homepage.
For TYPO3 documentation I am required to have extra documentation in a Documentation
folder. This means I have to maintain 2 documentations. Or not?
Answer: No. You have these 2 options:
README.rst (or .md) and a Documentation/Index.rst (for example).
This is done in our official manuals. The README.rst is not used as documentation,
it is used as an about the repo file. The README is mostly
used to direct users who come via GitHub (or Gitlab, Bitbucket etc.) to the rendered
documentation on docs.typo3.orgREADME.rst (or .md) as main documentation (Start page: Documentation/Index.rst) and
put everything in the README.rst . The Documentation/Settings.cfg file
must also exist, but that is all that needs to be in the Documentation
directory.Actually, you have more options, but we do not want to make things too complicated.
Which one should you choose? That is up to you.
We recommend: Use method 1) for extensive documentation with several chapters, use method 2) for minimal documentation which can be maintained in one file.
Why might you want an "Edit on GitHub" button on the rendered pages of your extension documentation?
"Edit on GitHub" button
It makes it easier to contribute to the documentation!
How do you enable this?
Just add this to your Settings: Documentation/guides.xml and customize it:
[html_theme_options]
# "Edit on GitHub" button
github_repository = TYPO3-Console/TYPO3-Console
github_branch = mainIf you used the sample extension and followed the steps in Use the init command to create the Documentation folder, you should actually already have this.
Look at the typo3_console extension for a working example.
Do you want contributors to find the issues for your extension easily when reading your extension documentation on docs.typo3.org?
Add project_ to your Settings: Documentation/guides.xml:
[html_theme_options]
project_issues = https://github.com/<user>/<extension-key>/issuesReplace <user> and <extension- with your username and extension key
or replace entire URL with URL to your issues.
A link to the Issues will then be available footer section.
Example extension: news
Get in touch with us, if you have problems, would like to ask questions or make suggestions.
Our team page contains information about how to contact us.
The documentation for system extensions is maintained inside the TYPO3 source code, so the contribution workflow is a little different.
For more information about the various contribution workflows, see Types of documentation.
Tip
There is an easy shortcut for minor changes: You can use the Edit on GitHub method for minor changes to system extensions documentation and the changelog. Under the hood, a patch will get created and pushed to Gerrit and you will find a comment in your pull request with information about where to find your patch on Gerrit.
See System Extensions for a list of system extension documentation.
Use the sample extension manual if you want to start new system extension documentation from scratch.
This chapter addresses contributing to third party extension documentation.
For system extensions, see Contribute to system extensions.
You can contribute to the documentation of any publicly available extension, if the repository is public (for example hosted on GitHub). This does not mean, the extension author will be willing or is obligated to merge your change. But, most of the time, useful contributions are welcome.
You can add issues or make changes via patches (for example pull requests on GitHub).
If you can make the change yourself, try to submit it as a patch instead of just writing an issue. It depends on the policy of the extension author (see contribution guide for specific repository, if available), but it is usually not required to write an issue. You can just submit a pull request (PR) directly.
First, you need to find out where the source is maintained. Usually, this will
be a repository on GitHub. There, you can also check if documentation is already
available. It should be a Documentation folder or one of the alternatives
mentioned in Prerequisites for rendering documentation to docs.typo3.org.
To find the repository, use one of these methods:
In the page of the rendered docs for the extension, click on Repository in the footer.
Sometimes the metadata in Settings.cfg in a Documentation project is not filled out and this link is missing. Then, you can use Method 2.
Select the extension
Click take a look in the code
You cannot find system extensions (extensions that are maintained in the core) on https://extensions.typo3.org. System extensions are for example indexed_search, form, impexp, etc.
You can also find the rendered documentation:
Go to: Extensions by extension key
Click on "Show Manual"
Note
You cannot find system extensions (extensions that are maintained in the core) on https://extensions.typo3.org.
Hopefully, the extension has a contribution guide. You can look at the GitHub help pages to check for conventions for contribution guides.
In the GitHub repository, you should find a file like:
If no contribution guide exists, follow the general conventions for TYPO3 documentation and conventions for creating pull requests on GitHub or contact the author.
README.rst or README.md Full documentation contains both a README. and a Documentation/
file. To avoid redundancy in both places, the README. 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>/ |Point out interesting statistics of your extension or package in the badges placeholder, which may 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.
The project placeholder contains the title of the project.
Common values are, for example, 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 topicand 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. and - if available - the description
fields of ext_ and composer..