4.7 KiB
4.7 KiB
RST Syntax Reference
Complete reStructuredText syntax reference for TYPO3 documentation.
Headings
=======================
Page title in sentence case
=======================
Section heading
===============
Subsection heading
------------------
Subsubsection heading
~~~~~~~~~~~~~~~~~~~~~
Paragraph heading
^^^^^^^^^^^^^^^^^
Rules:
- Page titles:
=above and below (must match title length) - Sections:
=below - Subsections:
-below - Subsubsections:
~below - Paragraphs:
^below - CRITICAL: Underline must be exactly the same length as the title text
- SENTENCE CASE: Use sentence case for all headlines, NOT title case
- ✅ Correct: "Mass approval on Crowdin", "API endpoints", "Best practices"
- ❌ Wrong: "Mass Approval On Crowdin", "API Endpoints", "Best Practices"
Inline Formatting
*italic text*
**bold text**
``code or literal text``
Code Blocks
PHP:
.. code-block:: php
<?php
$code = 'example';
YAML:
.. code-block:: yaml
setting: value
nested:
item: value
TypoScript:
.. code-block:: typoscript
config.tx_extension.setting = value
Bash:
.. code-block:: bash
composer install
JavaScript:
.. code-block:: javascript
const example = 'value';
Lists
Bullet Lists:
- First item.
- Second item.
- Nested item.
- Another nested.
Numbered Lists:
1. First item.
2. Second item.
3. Third item.
Definition Lists:
term
Definition of the term.
another term
Definition of another term.
Punctuation Rules:
- End with periods: All list items should end with a period (
.) - ✅ Correct:
1. Retrieve project metadata to get available languages. - ❌ Wrong:
1. Retrieve project metadata to get available languages - Exception: Single-word or very short items may omit periods for readability
Links
External Links:
`Link text <https://example.com>`__
Internal Cross-References:
.. _my-label:
Section Title
=============
Link to :ref:`my-label`
Link with custom text: :ref:`Custom Text <my-label>`
Documentation Links:
:ref:`t3tsref:start` (TYPO3 TS Reference)
:ref:`t3coreapi:start` (TYPO3 Core API)
Tables
Simple Table:
=========== ===========
Column 1 Column 2
=========== ===========
Row 1 Col 1 Row 1 Col 2
Row 2 Col 1 Row 2 Col 2
=========== ===========
Grid Table:
+------------+------------+
| Header 1 | Header 2 |
+============+============+
| Cell 1 | Cell 2 |
+------------+------------+
List Table:
.. list-table:: Table Title
:header-rows: 1
:widths: 20 80
* - Column 1
- Column 2
* - Value 1
- Value 2
Admonitions
.. note::
Additional information
.. important::
Important notice
.. warning::
Warning message
.. attention::
Attention required
.. tip::
Helpful tip
.. caution::
Caution advised
Images
.. image:: ../Images/screenshot.png
:alt: Alternative text
:width: 600px
:class: with-shadow
Figure with Caption:
.. figure:: ../Images/screenshot.png
:alt: Alternative text
:width: 600px
This is the caption text
Table of Contents
In-page TOC:
.. contents::
:local:
:depth: 2
Toctree (document hierarchy):
.. toctree::
:maxdepth: 2
:titlesonly:
:hidden:
Introduction/Index
Configuration/Index
API/Index
Comments
.. This is a comment
It can span multiple lines
and will not appear in the output
Line Blocks
| Line 1
| Line 2
| Line 3
Substitutions
.. |TYPO3| replace:: TYPO3 CMS
Using |TYPO3| in documentation...
Special Characters
\*literal asterisk\*
Whitespace Rules
- Blank lines: Required before and after directives
- Indentation: Use 3 spaces for directive content
- No trailing whitespace: Remove all trailing spaces
- Consistent indentation: Maintain same level within blocks
Common Mistakes
❌ Wrong underline length:
Section
==== # Too short
❌ Missing blank lines:
.. code-block:: php
$code = 'example'; # No blank line before content
❌ Incorrect indentation:
.. note::
Text # Only 2 spaces instead of 3
✅ Correct:
Section
=======
.. code-block:: php
$code = 'example';
.. note::
Text with 3-space indentation
References
- Sphinx RST Guide: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
- Docutils RST: https://docutils.sourceforge.io/rst.html
- TYPO3 Documentation Guide: https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/