Cheat sheet: reST & Sphinx¶

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

Cross referencing (:ref:)

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

[intersphinx_mapping]

h2document         = 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/Settings.cfg. 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)
ctrl + s (keyboard strokes)

Source:

:php:`$result = $a + 23;`
:typoscript:`lib.hello.value = Hello World!`
:file:`/etc/passwd`
: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
```
Two

Do something else ...

Source:

..  rst-class:: bignums

1.  Embed an image

    Source:

    ..  code-block:: rest

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

Do something else ...

Source:

..  rst-class:: bignums-xxl

1.  Embed an image

    Source:

    ..  code-block:: rest

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

2.  Two

    Do something else ...

Configuration values (confval)¶

How it looks:

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.

Source:

..  confval:: 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 Vendor\MyExtension\DateTime¶

Datetime class

setDate($year, $month, $day)¶

Set the date.

Parameters

$year (int) -- The year.
$month (int) -- The month.
$day (int) -- 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

Graphs ¶

How it looks:

Source:

..  graphviz::

    graph {
        user [
            shape=plaintext;
            width=4;
            label="User";
            style="";
        ]
        view [
            shape=box;
            width=4;
            label=<<B>View</B><BR/>Displaying the data>;
        ]
        controller [
            shape=box;
            width=4;
            label=<<B>Controller</B><BR/>Control of functionality>;
        ]
        model [
            shape=box;
            width=4;
            label=<<B>Model</B><BR/>Domain model and domain logic>;
        ]
        user -- view -- controller -- model;
    }

Diagrams ¶

How it looks:

Source:

..  uml::

    == Initialization ==

    Alice -> Bob: Authentication Request
    Bob --> Alice: Authentication Response

    == Repetition ==

    Alice -> Bob: Another authentication Request
    Alice <-- Bob: another authentication Response