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

# RST Syntax Reference

Complete reStructuredText syntax reference for TYPO3 documentation.

## Headings

```rst
=======================
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

```rst
*italic text*
**bold text**
``code or literal text``
```

## Code Blocks

**PHP:**
```rst
.. code-block:: php

   <?php
   $code = 'example';
```

**YAML:**
```rst
.. code-block:: yaml

   setting: value
   nested:
     item: value
```

**TypoScript:**
```rst
.. code-block:: typoscript

   config.tx_extension.setting = value
```

**Bash:**
```rst
.. code-block:: bash

   composer install
```

**JavaScript:**
```rst
.. code-block:: javascript

   const example = 'value';
```

## Lists

**Bullet Lists:**
```rst
- First item.
- Second item.

  - Nested item.
  - Another nested.
```

**Numbered Lists:**
```rst
1. First item.
2. Second item.
3. Third item.
```

**Definition Lists:**
```rst
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:**
```rst
`Link text <https://example.com>`__
```

**Internal Cross-References:**
```rst
.. _my-label:

Section Title
=============

Link to :ref:`my-label`
Link with custom text: :ref:`Custom Text <my-label>`
```

**Documentation Links:**
```rst
:ref:`t3tsref:start` (TYPO3 TS Reference)
:ref:`t3coreapi:start` (TYPO3 Core API)
```

## Tables

**Simple Table:**
```rst
===========  ===========
Column 1     Column 2
===========  ===========
Row 1 Col 1  Row 1 Col 2
Row 2 Col 1  Row 2 Col 2
===========  ===========
```

**Grid Table:**
```rst
+------------+------------+
| Header 1   | Header 2   |
+============+============+
| Cell 1     | Cell 2     |
+------------+------------+
```

**List Table:**
```rst
.. list-table:: Table Title
   :header-rows: 1
   :widths: 20 80

   * - Column 1
     - Column 2
   * - Value 1
     - Value 2
```

## Admonitions

```rst
.. note::
   Additional information

.. important::
   Important notice

.. warning::
   Warning message

.. attention::
   Attention required

.. tip::
   Helpful tip

.. caution::
   Caution advised
```

## Images

```rst
.. image:: ../Images/screenshot.png
   :alt: Alternative text
   :width: 600px
   :class: with-shadow
```

**Figure with Caption:**
```rst
.. figure:: ../Images/screenshot.png
   :alt: Alternative text
   :width: 600px

   This is the caption text
```

## Table of Contents

**In-page TOC:**
```rst
.. contents::
   :local:
   :depth: 2
```

**Toctree (document hierarchy):**
```rst
.. toctree::
   :maxdepth: 2
   :titlesonly:
   :hidden:

   Introduction/Index
   Configuration/Index
   API/Index
```

## Comments

```rst
.. This is a comment
   It can span multiple lines
   and will not appear in the output
```

## Line Blocks

```rst
| Line 1
| Line 2
| Line 3
```

## Substitutions

```rst
.. |TYPO3| replace:: TYPO3 CMS

Using |TYPO3| in documentation...
```

## Special Characters

```rst
\*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:**
```rst
Section
====  # Too short
```

❌ **Missing blank lines:**
```rst
.. code-block:: php
   $code = 'example';  # No blank line before content
```

❌ **Incorrect indentation:**
```rst
.. note::
  Text  # Only 2 spaces instead of 3
```

✅ **Correct:**
```rst
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/