ReST Cheat sheet: Using reStructuredText in TYPO3 Documentation
Cheat Sheet
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
-----------
There are more levels of headlines
References and linking
References to documentation from the TYPO3 world should be copied from the wizard:
They then look like this:
:ref:`Cheat sheet: reStructuredText <h2document:rest-cheat-sheet>`
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
The caption of the image
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\
Web > Page
typo3/cms-seo
More: 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\*