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 then one headlines consider to 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 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.

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:

..  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 menues: Configuration values (confval).

Figures and Images

..  figure:: /_Images/a4.jpg
    :alt: some image

    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 (bold, italic etc.).

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, 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\*