gh-netresearch-claude-code-marketplace-skills-typo3-docs/references/rst-syntax.md

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

1. Blank lines: Required before and after directives
2. Indentation: Use 3 spaces for directive content
3. No trailing whitespace: Remove all trailing spaces
4. 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/