Note

This version of the guide covers the new PHP-based rendering of Documentation with the TYPO3 Documentation theme.

If the project you are looking at has a file Documentation/guides.xml it is using the new rendering.

Otherwise, consider to migrate the Documentation or head over to the legacy version of this guide: How to document, Sphinx based.

Cheat sheet: reStructuredText

Headlines

Every reST (.rst) file should use these underlining styles. In reST, you can use different styles in any order you want. These are our conventions for TYPO3 documentation.

========
DocTitle
========

Then use underlining only:

..  _header1:

Header 1
========

Header 1.1
----------

Header 1.1.1
~~~~~~~~~~~~

Header 1.1.1.1
""""""""""""""

line 1-3: This is the doc title. Every .rst file should have one.
line 7: header label. This can be used for cross-referencing to this section:
```
:ref:`header1`
```
Copied!
9-10: Header level 1
etc.

Links

External links

method 1:

`anchor text <URL>`__

Check out more information on `t3o <https://typo3.org>`__.

(with one or two underscores at the end, if in doubt, use two)

method 2: "External Hyperlink Targets":

Check out more information on t3o_

_t3o: https://typo3.org

This may be more convenient if you use a link several times.

Cross references

When linking within docs.typo3.org, you should use this method of cross-referencing.

Use it to link to a section in this manual:

:ref:`intersphinx`

A section with the label intersphinx must exist! It is placed before the header:

..  _intersphinx:

Intersphinx
===========

Or, when cross-referencing to other manuals:

:ref:`shortcut:label`

References to TYPO3 documentation

When you are linking to another manual, make sure the shortcut (here: "h2document") is included in Settings: Documentation/guides.xml:

<inventory id="h2document"
            url="https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Index.html"
/>
...

We use the same conventions for naming the shortcuts in Settings.cfg, see Settings: Documentation/guides.xml. Not used manuals are commented out.

Tip

This is a cool feature, where reST & Sphinx shines: Even when a section is moved to another page (which effectively changes the URL), the link will still work!

ThisManual Link to: Same manual OtherManual Link to: Other manual
Explicit anchor text :ThisManual: :ref:`Cross Referencing <intersphinx>` :OtherManual: :ref:`Cross Referencing <t3docwrite:intersphinx>`
Automatic anchor text :ThisManual: :ref:`intersphinx` :OtherManual: :ref:`t3docwrite:intersphinx`

Preventing links

Prevent unintentional linking of simple URLs with the :samp: directive:

The TYPO3 backend can be accessed via :samp:`https://example.org/typo3` ..

and emphasize parts of the URL with curly braces:

The *route* is the "speaking URL" as a whole without the domain part,
for example :samp:`https://example.org/{<path>}`.

Hypothetical domains

If the domain name of an URL does not matter, but serves as a placeholder, choose from this list of dummy domains – in this order:

https://example.org
https://example.com
https://example.net

and use for explicit mention of the local development context:

https://example.localhost.

For further dummy domains use subdomains of the domains listed above such as

https://staging.example.org
https://production.example.org.

Lists

How it looks:

To create a bullet list:

add a blank line before and after the list
indent the list item text by 4 spaces - including the item sign
to create a nested list:
- indent the items by 4 spaces (left-align with parent item text)
- apply rules of parent list (blank lines, item text indentation, ..)

More text.

Source:

To create a bullet list:

*   add a blank line before and after the list
*   indent the list item text by 4 spaces - including the item sign
*   to create a nested list:

    *   indent the items by 4 spaces (left-align with parent item text)
    *   apply rules of parent list (blank lines, item text indentation, ..)

More text.

Numbered lists

How it looks:

To create a numbered list:

add a blank line before and after the list
indent the list item text by 4 spaces - including the item sign
to create a nested list:
1. indent the items by 4 spaces (left-align with parent item text)
2. apply rules of parent list (blank lines, item text indentation, ..)

More text.

Source:

To create a numbered list:

#.  add a blank line before and after the list
#.  indent the list item text by 4 spaces - including the item sign
#.  to create a nested list:

    #. indent the items by 4 spaces (left-align with parent item text)
    #. apply rules of parent list (blank lines, item text indentation, ..)

More text.

Code Blocks

Important

Use syntactically correct code in your code blocks.

Code block directive

How it looks:

$a = 'hello';
$b = 'something';

Source:

..  code-block:: php

    $a = 'hello';
    $b = 'something';

This uses the directive "code-block" (line 1)

Important

Make sure to indent correctly. The lines of the code-block (line 3+) must be indented (4 spaces).

Placeholders

Use the Backus-Naur form like <placeholder-name> for placeholders in code and URLs.

Examples:

class <Entity>Controller extends ActionController
typo3/sysext/core/bin/typo3 impexp:import <file>
https://example.org/typo3/main?token=<token-id>

For XML and HTML, use the comment tag .

Inline code, text roles

For inline code or for other semantic markup of special texts, use text roles.

How it looks:

$result = $a + 23; (PHP snippet)
lib.hello.value = Hello World! (TypoScript snippets)
/etc/passwd (file)
bin/typo3 cleanup:flexforms (shell)
tt_content.pi_flexform (SQL)
<TCEForms> (XML)
ctrl + s (keyboard strokes)

Source:

:php:`$result = $a + 23;`
:typoscript:`lib.hello.value = Hello World!`
:file:`/etc/passwd`
:bash:`bin/typo3 cleanup:flexforms` (shell)
:sql:`tt_content.pi_flexform` (SQL)
:xml:`<TCEForms>` (XML)
:kbd:`ctrl` + :kbd:`s`

Bold & italic

How it looks:

Normal text, bold text and italic text.

Source:

Normal text, **bold text** and *italic text*.

Images

How it looks:

Source:

..  image:: /_Images/a4.jpg
    :class: with-shadow

Another example:

..  image:: /_Images/a4.jpg
    :class: with-shadow
    :target: https://typo3.org
    :alt: alt text
    :width: 100px

YouTube videos

How it looks:

Source:

..  youtube:: wNxO-aXY5Yw

Styled numbered lists

This is often used, for a Quick Start section, involving a few numbered steps:

With Big Numbers

This is an example with a code block (::) embedded in the sections.

How it looks:

Embed an image

Source:
```
/_Images/a4.jpg
    :class: with-shadow
```
Copied!
Two

Do something else ...

Source:

..  rst-class:: bignums

1.  Embed an image

    Source:

    ..  code-block:: rst

        ..  image: some_image.png
            :class: with-shadow

2.  Two

    Do something else ...

With Big Numbers XXL

How it looks:

Embed an image

Source:
```
/_Images/a4.jpg
    :class: with-shadow
```
Copied!
Two

Do something else ...

Source:

..  rst-class:: bignums-xxl

1.  Embed an image

    Source:

    ..  code-block:: rst

        ..  image: some_image.png
            :class: with-shadow

2.  Two

    Do something else ...

Configuration values (confval)

How it looks:

title

Type: string or LLL reference
Required: true
Scope: Display
Path: $GLOBALS > TCA > [table] > columns > [field]

The name of the field as shown in the form.

Source:

..  confval:: title
    :name: unique-title
    :required: true
    :type: string or LLL reference
    :Scope: Display
    :Path: $GLOBALS > TCA > [table] > columns > [field]

    The name of the field as shown in the form.

PHP domain

How it looks:

class DateTime

Fully qualified name: \Vendor\MyExtension\DateTime

Datetime class

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.

Source:

..  php:namespace::  Vendor\MyExtension

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

Tips, hints, important (Admonitions)

Visit Admonitions: Tip, Note, Warning, See also, etc to see the available admonitions.

How it looks:

Tip

To look at the reST source of this rendered page, scroll to the top and click on View source.

Source:

..  tip::

    To look at the reST source of this rendered page, scroll to the bottom
    and click on "View page source".

Cards

How it looks:

Pages

The Page Management Guide introduces TYPO3's Page Tree and explains how pages are created and managed.

11

Source:

..  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:`Pages <t3editors:pages>`

        ..  container:: card-body

            The Page Management Guide introduces TYPO3's Page Tree and explains how pages are created and managed.

        ..  container:: card-footer pb-0

            ..  rst-class:: horizbuttons-striking-m

            -  `11 <https://docs.typo3.org/m/typo3/tutorial-editors/11.5/en-us/Pages/Index.html>`__

Tabs

How it looks:

touch example-project-directory/public/FIRST_INSTALL

echo $null >> public/FIRST_INSTALL

Source:

..  tabs::

    ..  group-tab:: bash

        ..  code-block:: bash

            touch example-project-directory/public/FIRST_INSTALL

    ..  group-tab:: powershell

        ..  code-block:: powershell

            echo $null >> public/FIRST_INSTALL

Diagrams

How it looks:

Some Caption

Source:

Documentation/SomeFile.rst

..  uml::
    :caption: Some Caption

    class -> otherClass : message

Sidebar

Source / How it looks:

..  sidebar:: reST content elements

    * :ref:`Cards <rest-cards>`
    * :ref:`Tabs <rest-tabs>`
    * :ref:`Configuration values <rest-confval>`