003 Name Skill 347ed253

---
name: typo3-docs
description: >-
  Create and maintain TYPO3 extension documentation following official docs.typo3.org
  standards. RST syntax, TYPO3 directives, rendering, and deployment. Use when working
  with documentation, rst, docs, readme, typo3 documentation.
compatibility: TYPO3 13.0 - 14.x
metadata:
  version: "1.0.0"
---

# TYPO3 Documentation Skill

Create and maintain TYPO3 extension documentation following official docs.typo3.org standards.

> **TYPO3 API First:** Always use TYPO3's built-in APIs, core features, and established conventions before creating custom implementations. Do not reinvent what TYPO3 already provides. Always verify that the APIs and methods you use exist and are not deprecated in your target TYPO3 version (v13 or v14) by checking the official TYPO3 documentation.

## When to Use

- Creating documentation from scratch (no `Documentation/` exists)
- Editing `Documentation/**/*.rst` files
- Using TYPO3 directives: `confval`, `versionadded`, `card-grid`, `tabs`
- Creating/adding screenshots
- Rendering and testing documentation locally
- Deploying to docs.typo3.org

## Documentation Structure

```
Documentation/
├── Index.rst                 # Main entry point
├── guides.xml                # Configuration file
├── Introduction/
│   └── Index.rst
├── Installation/
│   └── Index.rst
├── Configuration/
│   └── Index.rst
├── Usage/
│   └── Index.rst
├── Developer/
│   └── Index.rst
└── Images/
    └── screenshot.png
```

## Creating Documentation from Scratch

When no `Documentation/` directory exists, use the init command:

```bash
docker run --rm --pull always -v $(pwd):/project -it \
  ghcr.io/typo3-documentation/render-guides:latest init
```

**Interactive prompts:**
1. **Format**: Choose `rst` (ReStructuredText) for full TYPO3 theme features
2. **Site Set**: Enter name/path if extension defines a Site set

## guides.xml Configuration

```xml
<?xml version="1.0" encoding="UTF-8"?>
<guides xmlns="https://www.phpdoc.org/guides" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://www.phpdoc.org/guides https://docs.typo3.org/render-guides/guides.xsd">
    <project title="My Extension"/>
    <extension name="my_extension"/>
</guides>
```

### With GitHub Integration

```xml
<?xml version="1.0" encoding="UTF-8"?>
<guides xmlns="https://www.phpdoc.org/guides" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://www.phpdoc.org/guides https://docs.typo3.org/render-guides/guides.xsd">
    <project title="My Extension" version="1.0.0"/>
    <extension name="my_extension"/>
    <inventory id="t3coreapi" url="https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/"/>
    <settings>
        <setting name="edit_on_github" value="https://github.com/vendor/my-extension/edit/main/Documentation/"/>
        <setting name="edit_on_github_branch" value="main"/>
    </settings>
</guides>
```

## RST Syntax Reference

### Headings

```rst
==========
Page Title
==========

Section
=======

Subsection
----------

Subsubsection
~~~~~~~~~~~~~
```

### Code Blocks

```rst
..  code-block:: php
    :caption: Classes/Service/MyService.php

    <?php
    declare(strict_types=1);

    namespace Vendor\MyExtension\Service;

    final class MyService
    {
        // ...
    }
```

### Inline Code and Text Roles

```rst
Use :php:`MyClass` for PHP references.
The file :file:`ext_localconf.php` is loaded automatically.
Click :guilabel:`Save` to apply changes.
Press :kbd:`Ctrl+S` to save.
```

### Links and References

```rst
See :ref:`my-reference-label` for more information.

External link: `TYPO3 Documentation <https://docs.typo3.org/>`__

..  _my-reference-label:

Section with Reference
======================

This section can be referenced from anywhere.
```

## TYPO3 Directives

### confval (Configuration Values)

```rst
..  confval:: encryptionMethod
    :name: ext-myext-encryptionMethod
    :type: string
    :default: 'aes-256-gcm'
    :required: false

    The encryption method to use for API keys.

    Available options:

    -   ``aes-256-gcm`` (recommended)
    -   ``aes-256-cbc``
```

### versionadded / versionchanged / deprecated

```rst
..  versionadded:: 2.0.0
    This feature was added in version 2.0.0.

..  versionchanged:: 2.1.0
    The default value was changed from ``false`` to ``true``.

..  deprecated:: 3.0.0
    Use :php:`newMethod()` instead.
```

### Admonitions

```rst
..  note::
    Background information users should know.

..  tip::
    Helpful suggestion for better results.

..  warning::
    Potential issue or data loss risk.

..  important::
    Critical information that must not be missed.
```

### Tabs

```rst
..  tabs::

    ..  group-tab:: Composer

        Install via Composer:

        ..  code-block:: bash

            composer require vendor/my-extension

    ..  group-tab:: TER

        Download from the TYPO3 Extension Repository.
```

### Card Grid

```rst
..  card-grid::
    :columns: 2
    :card-height: 100

    ..  card:: Installation

        Learn how to install the extension.

        :ref:`Read more <installation>`

    ..  card:: Configuration

        Configure the extension for your needs.

        :ref:`Read more <configuration>`
```

### Accordion

```rst
..  accordion::

    ..  accordion-item:: How do I install this extension?

        See the :ref:`installation` chapter.

    ..  accordion-item:: What PHP version is required?

        PHP 8.2 or higher is required.
```

## Editor Configuration

Create `Documentation/.editorconfig`:

```editorconfig
root = true

[*]
charset = utf-8
end_of_line = lf
indent_style = space
indent_size = 4
insert_final_newline = true
trim_trailing_whitespace = true
max_line_length = 80
```

## Rendering Documentation

### Local Rendering

```bash
# Render documentation
docker run --rm --pull always -v $(pwd):/project -it \
  ghcr.io/typo3-documentation/render-guides:latest

# Output is in Documentation-GENERATED-temp/
```

### With Live Preview

```bash
# Start watch mode for live preview
docker run --rm --pull always -v $(pwd):/project -p 8080:8080 -it \
  ghcr.io/typo3-documentation/render-guides:latest --watch

# Open http://localhost:8080 in browser
```

### Validation

```bash
# Validate RST syntax
docker run --rm --pull always -v $(pwd):/project -it \
  ghcr.io/typo3-documentation/render-guides:latest --no-progress --fail-on-log
```

## Screenshots

### Requirements
- PNG format
- 72 DPI
- Appropriate size (not too large)
- Always include `:alt:` text

### Adding Screenshots

```rst
..  figure:: /Images/BackendModule.png
    :alt: Backend module screenshot
    :class: with-shadow

    The backend module provides an overview of all items.
```

### Screenshot Directory

```
Documentation/
└── Images/
    ├── BackendModule.png
    ├── Configuration.png
    └── Frontend.png
```

## Writing Guidelines

### General Rules
- Use **American English** spelling (color, behavior, optimize)
- Use **sentence case** for headings (not Title Case)
- Maximum line length: **80 characters**
- Use **4 spaces** for indentation (no tabs)
- Add blank line before and after code blocks
- Use present tense

### CamelCase for Files
- `Index.rst` (not `index.rst`)
- `Configuration/` (not `configuration/`)
- `BackendModule.png` (not `backend-module.png`)

### Example: Good Documentation

```rst
============
Installation
============

This chapter explains how to install the extension.

Requirements
============

-   TYPO3 v13.4 or v14.x
-   PHP 8.2 or higher

Installation via Composer
=========================

Run the following command:

..  code-block:: bash

    composer require vendor/my-extension

After installation, activate the extension:

..  code-block:: bash

    vendor/bin/typo3 extension:activate my_extension
```

## Deployment to docs.typo3.org

### Prerequisites
1. Extension registered on extensions.typo3.org
2. Documentation in `Documentation/` directory
3. Valid `guides.xml` configuration

### Webhook Setup

1. Go to https://intercept.typo3.com/
2. Login with TYPO3.org account
3. Register your repository
4. Add webhook to GitHub/GitLab

### Trigger Rendering

Documentation is automatically rendered when:
- Webhook receives push event
- Manual trigger via Intercept

## Complete Index.rst Example

```rst
..  include:: /Includes.rst.txt

.. _start:

==============
My Extension
==============

:Extension key:
    my_extension

:Package name:
    vendor/my-extension

:Version:
    |release|

:Language:
    en

:Author:
    Your Name

:License:
    This document is published under the
    `Creative Commons BY 4.0 <https://creativecommons.org/licenses/by/4.0/>`__
    license.

:Rendered:
    |today|

----

This extension provides functionality for managing items.

----

**Table of Contents**

..  toctree::
    :maxdepth: 2
    :titlesonly:

    Introduction/Index
    Installation/Index
    Configuration/Index
    Usage/Index
    Developer/Index

..  toctree::
    :hidden:

    Sitemap
```

## Resources

- **TYPO3 Documentation Guide**: https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/
- **RST Primer**: https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/WritingReST/
- **Render Guides**: https://github.com/TYPO3-Documentation/render-guides
- **Intercept**: https://intercept.typo3.com/

---

## Credits & Attribution

Thanks to Netresearch DTT GmbH for their contributions to the TYPO3 community.