--- title: "reST cheat sheet: using reStructuredText in TYPO3 documentation" manual: "How to Document" version: "main" permalink: "https://docs.typo3.org/permalink/h2document:rest-cheat-sheet" source: "Basics/RstCheatSheet.rst" modified: "2026-09-14T09:38:54+00:00" --- # reST cheat sheet: using reStructuredText in TYPO3 documentation **Cheat Sheet** - [Headlines and anchors](https://docs.typo3.org/permalink/h2document:headlines-and-anchors) - [Contents menu](https://docs.typo3.org/permalink/h2document:contents-menu) - [References and linking](https://docs.typo3.org/permalink/h2document:references-and-linking) - [Code blocks](https://docs.typo3.org/permalink/h2document:code-blocks) - [Configuration values (confvals)](https://docs.typo3.org/permalink/h2document:configuration-values-confvals) - [Figures and images](https://docs.typo3.org/permalink/h2document:figures-and-images) - [Lists, ordered and unordered](https://docs.typo3.org/permalink/h2document:lists-ordered-and-unordered) - [Inline text roles](https://docs.typo3.org/permalink/h2document:inline-text-roles) - [Comments](https://docs.typo3.org/permalink/h2document:comments) - [Escape characters](https://docs.typo3.org/permalink/h2document:escape-characters) ## Headlines and anchors Each reST document must have a title. It is overlined and underlined like this: **Documentation/MyDocs.rst** ```plaintext .. _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](https://docs.typo3.org/permalink/h2document:headlines-and-sections) ## 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: ```rst .. contents:: ``` Additional options are possible: [contents menu options](https://docs.typo3.org/permalink/h2document:content-menu). ## References and linking References to documentation from the TYPO3 world should be copied from the wizard: ![](../_Images/link-headlines.png) They then look like this: ```rst `ReST Cheat sheet `_ ``` Permalinks are resolved during rendering, but not every broken one is reported: see [Permalinks](https://docs.typo3.org/permalink/h2document: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: ```rst See also https://www.typo3.org or `the TER `_. ``` 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:`): ```rst 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: [Links in ReStructured text](https://docs.typo3.org/permalink/h2document:links). ## Code blocks Short code blocks can be inserted directly into a reST file: ```rst .. 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: ```rst .. literalinclude:: /snippets/_HelloWorld.php :caption: EXT:my_extension/Classes/WorldDominance/HelloWorld.php ``` All [options of code blocks](https://docs.typo3.org/permalink/h2document:codeblock-quick-reference) can also be applied to literal includes. ## Configuration values (confvals) Configuration values can be defined like this: ```rst .. 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)](https://docs.typo3.org/permalink/h2document:rest-confval). ## Figures and images **Documentation/MyDocs.rst** ```plaintext .. figure:: /_Images/a4.jpg :alt: some image This is the image caption ``` - [Images in reST](https://docs.typo3.org/permalink/h2document:images) - [Guidelines for creating images](https://docs.typo3.org/permalink/h2document:guidelines-for-images) ## Lists, ordered and unordered ```rst * 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](https://docs.typo3.org/permalink/h2document:rest-lists). ## Inline text roles ```rst *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`](https://packagist.org/packages/typo3/cms-seo) More: [Basic inline markup (bold, italic etc.)](https://docs.typo3.org/permalink/h2document:rest-bold-italic). ## Comments Comments can be written like this: ```rst .. this is a comment .. with another line ``` Or like this: ```rst .. 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 (`\\`). ```rst \*not italic\* \`not a text role\` \_not\_a\_reference \\literal backslash ``` Looks like this: \*not italic\*\ \`not a text role\`\ \_not_a_reference\ \\literal backslash > [!NOTE] > Inside [code blocks](https://docs.typo3.org/permalink/h2document:writing-rest-codeblocks-with-syntax-highlighting) > and inline code (backticks), escaping is not needed — content is displayed > literally.