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
""""""""""""""
Copied!
  • 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.

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

Numbered lists

How it looks:

To create a numbered list:

  1. add a blank line before and after the list
  2. indent the list item text by 4 spaces - including the item sign
  3. 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.
Copied!

Code Blocks

Code block directive

How it looks:

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

Source:

..  code-block:: php

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

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

Placeholders

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

Examples:

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

For XML and HTML, use the comment tag <!-- placeholder-name -->.

Inline code, text roles

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

How it looks:

  1. $result = $a + 23; (PHP snippet)
  2. lib.hello.value = Hello World! (TypoScript snippets)
  3. /etc/passwd (file)
  4. bin/typo3 cleanup:flexforms (shell)
  5. tt_content.pi_flexform (SQL)
  6. <TCEForms> (XML)
  7. 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`
Copied!

Bold & italic

How it looks:

Normal text, bold text and italic text.

Source:

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

Images

How it looks:

Source:

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

Another example:

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

YouTube videos

How it looks:

Source:

..  youtube:: wNxO-aXY5Yw
Copied!

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:

  1. Embed an image

    Source:

    /_Images/a4.jpg
        :class: with-shadow
    Copied!
  2. 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 ...
Copied!

With Big Numbers XXL

How it looks:

  1. Embed an image

    Source:

    /_Images/a4.jpg
        :class: with-shadow
    Copied!
  2. 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 ...
Copied!

Configuration values (confval)

See also: Configuration values (confval).

How it looks:

title

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

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

Tips, hints, important (Admonitions)

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

How it looks:

Source:

..  tip::

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

Cards

How it looks:

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

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>`__
Copied!

Tabs

How it looks:

touch example-project-directory/public/FIRST_INSTALL
Copied!
echo $null >> public/FIRST_INSTALL
Copied!

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
Copied!

Diagrams

How it looks:

classclassotherClassotherClassmessage
Some Caption

Source:

Documentation/SomeFile.rst
..  uml::
    :caption: Some Caption

    class -> otherClass : message
Copied!

Sidebar

Source / How it looks:

..  sidebar:: reST content elements

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