reST cheat sheet: using reStructuredText in TYPO3 documentation 

Headlines and anchors 

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

Contents menu 

If you use more than one headline, provide a contents menu. It also allows your users to collapse all sections and only open the one they are reading:

..  contents::

Additional options are possible: contents menu options.

References and linking 

References to documentation from the TYPO3 world should be copied from the wizard:

They then look like this:

`ReST Cheat sheet <https://docs.typo3.org/permalink/h2document:rest-cheat-sheet>`_

Permalinks are the preferred way to link TYPO3 documentation. See Permalinks for the three rules a hand-written permalink has to follow.

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 (link to the package) and PHP classes (link to the API documentation). PHP classes can be displayed in either FQN format ( :php:) or classname only (:php-short:):

Install :composer:`typo3/cms-seo` to listen to event
:php:`\TYPO3\CMS\Seo\Event\ModifyUrlForCanonicalTagEvent`
:php-short:`\TYPO3\CMS\Seo\Event\ModifyUrlForCanonicalTagEvent`

There is a dedicated chapter on links and references in reST.

Code blocks 

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. By convention, the underscore marks the file as an example, so that nobody mistakes it for real code. It also keeps the file apart from the reST files of its directory:

..  literalinclude:: /snippets/_HelloWorld.php
    :caption: EXT:my_extension/Classes/WorldDominance/HelloWorld.php

All options of code blocks can also be applied to literal includes.

Configuration values (confvals) 

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

Figures and images 

..  figure:: /_Images/a4.jpg
    :alt: A spiral staircase seen from above, with people walking up and
        down the steps

    This is the image caption

• Images in reST
• Guidelines for creating images

Lists, ordered and unordered 

*   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.
#.  list

More about Lists.

Inline text roles 

*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\CMS\Seo\Event\ModifyUrlForCanonicalTagEvent Web > Page typo3/cms-seo

More: basic inline markup.

Comments 

Comments can be written like this:

..  this is a comment
..  with another line

Or like this:

..  this is a comment
    with another line

Escape characters 

If you want to use a character that would normally create reST markup, you must escape it with a prepended backslash ( \\ ).

\*not italic\*
\`not a text role\`
\_not\_a\_reference
\\literal backslash

Looks like this: