Skip to content

netresearch/typo3-docs-skill / skills/typo3-docs

typo3-docs

Flagged

Use when TYPO3 extension documentation has to render on docs.typo3.org, which builds a manual from Documentation/guides.xml and reads no Settings.cfg (a single README.rst serves an extension too small for one): when an extension has no documentation yet, or when creating, editing or reviewing Documentation/*.rst, guides.xml, README.md or XLF translations, rendering docs with Docker, TYPO3 RST directives, screenshots, or XLIFF 2-space indentation (TYPO3 v14+).

FileKindSize
SKILL.mdskill md5.9 KB
assets/AGENTS.mdmarkdown11.7 KB
assets/guides.xml.distother1.8 KB
checkpoints.yamlconfig43.1 KB
evals/evals.jsonconfig23.1 KB
references/architecture-decision-records.mdmarkdown6.6 KB
references/asset-templates-guide.mdmarkdown2.8 KB
references/canonical-sources.mdmarkdown6.2 KB
references/code-structure-elements.mdmarkdown7.4 KB
references/coding-guidelines.mdmarkdown7.1 KB
references/content-directives.mdmarkdown7.6 KB
references/documentation-coverage-analysis.mdmarkdown7.6 KB
references/documentation-quality-checks.mdmarkdown3.5 KB
references/extraction-patterns.mdmarkdown23.3 KB
references/file-structure.mdmarkdown7.0 KB
references/guides-xml.mdmarkdown15.9 KB
references/intercept-deployment.mdmarkdown12.5 KB
references/render-guides-development.mdmarkdown8.8 KB
references/rendering.mdmarkdown17.3 KB
references/rst-syntax.mdmarkdown10.5 KB
references/screenshots.mdmarkdown13.1 KB
references/scripts-guide.mdmarkdown3.1 KB
references/text-roles-inline-code.mdmarkdown2.5 KB
references/typo3-directives.mdmarkdown16.0 KB
references/typo3-extension-architecture.mdmarkdown17.4 KB
references/upstream-docs-contribution.mdmarkdown7.5 KB
scripts/add-agents-md.shexecutablescript2.2 KB
scripts/analyze-docs.shexecutablescript12.0 KB
scripts/check-adr-coverage.shexecutablescript778 B
scripts/check-changelog-version-coverage.shexecutablescript1.7 KB
scripts/check-confval-completeness.shexecutablescript2.1 KB
scripts/check-guides-xml-schema.shexecutablescript4.0 KB
scripts/check-guides-xml-version-sync.shexecutablescript1.9 KB
scripts/check-required-doc-sections.shexecutablescript1.6 KB
scripts/check-rst-substitutions-resolve.shexecutablescript5.4 KB
scripts/check-screenshot-freshness.shexecutablescript2.5 KB
scripts/check-settings-documented.shexecutablescript1.5 KB
scripts/check-ui-surface-screenshots.shexecutablescript2.8 KB
scripts/check-untranslated-fluid-strings.shexecutablescript1.6 KB
scripts/check-version-match.shexecutablescript624 B
scripts/extract-all.shexecutablescript4.1 KB
scripts/extract-build-configs.shexecutablescript2.8 KB
scripts/extract-composer.shexecutablescript1.9 KB
scripts/extract-extension-config.shexecutablescript5.0 KB
scripts/extract-php.shexecutablescript5.1 KB
scripts/extract-project-files.shexecutablescript2.0 KB
scripts/extract-repo-metadata.shexecutablescript4.7 KB
scripts/extraction-dir.shexecutablescript1.7 KB
scripts/json-string.shscript921 B
scripts/render_docs.shexecutablescript1.0 KB
scripts/validate_docs.shexecutablescript6.2 KB
scripts/validate_headings.pyexecutablescript4.4 KB

references/typo3-extension-architecture.md

View on GitHub
<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
<!-- SPDX-FileCopyrightText: Netresearch DTT GmbH -->

# TYPO3 Extension Architecture Reference

Extension file inventory annotated for **documentation extraction weighting**
(this skill's own model). **Canonical source for the extension file structure
itself (wins on conflict — see `canonical-sources.md`):**
[Core API: Files and locations](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/FileStructure/Index.html)
`[upstream]`.

The inventory below is **not exhaustive** — it lists only the files this
skill's extraction pipeline weighs. For the complete, current inventory
(incl. `ext_tables_static+adt.sql`, `ext_typoscript_*.typoscript`,
`Configuration/Fluid/`, `ContentSecurityPolicies.php`,
`RequestMiddlewares.php`, `page.tsconfig`/`user.tsconfig`) read the upstream
page. The Priority/Extract/Map/Weight annotations are `[heuristic]`
(skill-owned extraction model, not a TYPO3 statement).

## File Structure Hierarchy

### šŸ”“ Required Files (High Priority)

**composer.json** - Composer configuration
- **Documentation Priority:** HIGH
- **Extract:** Package name, description, dependencies, autoload configuration
- **Map to RST:** Introduction/Index.rst (overview), Installation requirements
- **Weight:** Critical for dependency documentation

**ext_emconf.php** - Extension metadata
- **Documentation Priority:** HIGH
- **Extract:** Title, description, version, author, constraints
- **Map to RST:** Introduction/Index.rst, guides.xml (or Settings.cfg)
- **Weight:** Essential metadata, version constraints

**Index.rst** (in Documentation/)
- **Documentation Priority:** CRITICAL
- **Required:** Main documentation entry point
- **Must Exist:** For TYPO3 Intercept deployment

**guides.xml** (in Documentation/) - Modern, Preferred
- **Documentation Priority:** CRITICAL
- **Required:** Documentation build configuration (PHP-based rendering)
- **Must Exist:** For TYPO3 Intercept deployment
- **Note:** Modern format, preferred over Settings.cfg

**Settings.cfg** (in Documentation/) - Legacy
- **Documentation Priority:** CRITICAL (if guides.xml not present)
- **Required:** Documentation build configuration (Sphinx-based)
- **Note:** Legacy format, migrate to guides.xml for modern rendering

### 🟔 Core Structure Files (Medium-High Priority)

**ext_localconf.php** - Runtime configuration
- **Documentation Priority:** MEDIUM-HIGH
- **Extract:** Plugin registrations, hooks, service configurations
- **Map to RST:** Integration guides, Developer/Configuration.rst
- **Weight:** Important for integration documentation

**ext_tables.php** - Backend configuration — **deprecated upstream**: the
Core API marks it "(Deprecated)"; modern extensions register backend modules
and TCA via `Configuration/` instead. When documenting an extension that still
ships one, note the migration.
- **Documentation Priority:** MEDIUM
- **Extract:** Backend module registrations, permissions
- **Map to RST:** Developer/Backend.rst
- **Weight:** Backend-specific documentation

**ext_tables.sql** - Database schema
- **Documentation Priority:** MEDIUM
- **Extract:** Table structures, field definitions
- **Map to RST:** Developer/Database.rst, API/DataModel.rst
- **Weight:** Important for database documentation

**ext_conf_template.txt** - Extension configuration template
- **Documentation Priority:** HIGH
- **Extract:** All configuration options, types, defaults, security warnings
- **Map to RST:** Integration/Configuration.rst (confval directives)
- **Weight:** Critical - direct user-facing configuration

## Directory Structure Weights

### Classes/ (Weight: HIGH)

**Purpose:** PHP source code following PSR-4 autoloading

**Priority Hierarchy:**

1. **Classes/Controller/** (Weight: HIGH)
   - **Documentation Priority:** HIGH
   - **Extract:** Action methods, parameters, return types
   - **Map to RST:** API/Controllers/, Developer/Plugins.rst
   - **Pattern:** MVC controllers extending `ActionController`

2. **Classes/Domain/Model/** (Weight: HIGH)
   - **Documentation Priority:** HIGH
   - **Extract:** Entity properties, getters/setters, relationships
   - **Map to RST:** API/Models/, Developer/DataModel.rst
   - **Pattern:** Extbase domain models

3. **Classes/Domain/Repository/** (Weight: MEDIUM-HIGH)
   - **Documentation Priority:** MEDIUM-HIGH
   - **Extract:** Query methods, custom finders
   - **Map to RST:** API/Repositories/, Developer/DataAccess.rst
   - **Pattern:** Extends `\TYPO3\CMS\Extbase\Persistence\Repository`

4. **Classes/ViewHelpers/** (Weight: MEDIUM)
   - **Documentation Priority:** MEDIUM
   - **Extract:** ViewHelper arguments, usage examples
   - **Map to RST:** Developer/ViewHelpers.rst
   - **Pattern:** Custom Fluid ViewHelpers

5. **Classes/Utility/** (Weight: MEDIUM)
   - **Documentation Priority:** MEDIUM
   - **Extract:** Utility methods, static helpers
   - **Map to RST:** API/Utilities/
   - **Pattern:** Static helper classes

6. **Classes/Service/** (Weight: MEDIUM-HIGH)
   - **Documentation Priority:** MEDIUM-HIGH
   - **Extract:** Service methods, dependencies
   - **Map to RST:** API/Services/
   - **Pattern:** Business logic services

### Configuration/ (Weight: VERY HIGH)

**Purpose:** All TYPO3 configuration files

**Priority Hierarchy:**

1. **Configuration/TCA/** (Weight: VERY HIGH)
   - **Documentation Priority:** VERY HIGH
   - **Extract:** Table definitions, field configurations, relationships
   - **Map to RST:** Developer/DataModel.rst, Editor/Fields.rst
   - **Files:** `<tablename>.php`
   - **Pattern:** Database table configuration arrays

2. **Configuration/TCA/Overrides/** (Weight: HIGH)
   - **Documentation Priority:** HIGH
   - **Extract:** Field additions, modifications to core tables
   - **Map to RST:** Integration/CoreExtensions.rst
   - **Files:** `<tablename>.php`
   - **Pattern:** TCA modifications

3. **Configuration/TypoScript/** (Weight: HIGH)
   - **Documentation Priority:** HIGH
   - **Extract:** Constants, setup, plugin configurations
   - **Map to RST:** Configuration/TypoScript.rst
   - **Files:** `constants.typoscript`, `setup.typoscript`
   - **Pattern:** TypoScript configuration

4. **Configuration/Sets/** (Weight: HIGH)
   - **Documentation Priority:** HIGH
   - **Extract:** Site set configurations, settings definitions
   - **Map to RST:** Configuration/SiteSets.rst
   - **Files:** `config.yaml`, `settings.definitions.yaml`, `setup.typoscript`
   - **Pattern:** Modern configuration approach (TYPO3 v13+)

5. **Configuration/TsConfig/** (Weight: MEDIUM-HIGH)
   - **Documentation Priority:** MEDIUM-HIGH
   - **Extract:** Page TSconfig, User TSconfig
   - **Map to RST:** Editor/PageTSconfig.rst, Editor/UserTSconfig.rst
   - **Subdirs:** `Page/`, `User/`
   - **Files:** `*.tsconfig`

6. **Configuration/Backend/** (Weight: MEDIUM)
   - **Documentation Priority:** MEDIUM
   - **Extract:** Backend routes, modules, AJAX routes
   - **Map to RST:** Developer/Backend.rst
   - **Files:** `Routes.php`, `Modules.php`, `AjaxRoutes.php`

7. **Configuration/Services.yaml** (Weight: HIGH)
   - **Documentation Priority:** HIGH
   - **Extract:** DI configuration, event listeners, console commands
   - **Map to RST:** Developer/DependencyInjection.rst, Developer/Events.rst
   - **Pattern:** Symfony-style service configuration

8. **Configuration/Extbase/Persistence/Classes.php** (Weight: MEDIUM)
   - **Documentation Priority:** MEDIUM
   - **Extract:** Model-to-table mappings
   - **Map to RST:** Developer/Persistence.rst

9. **Configuration/Icons.php** (Weight: LOW)
   - **Documentation Priority:** LOW
   - **Extract:** Icon identifiers
   - **Map to RST:** Developer/Icons.rst (if comprehensive)

### Resources/ (Weight: MEDIUM)

**Purpose:** Asset files and templates

**Priority Hierarchy:**

1. **Resources/Private/Language/** (Weight: MEDIUM-HIGH)
   - **Documentation Priority:** MEDIUM
   - **Extract:** Translation keys (for reference)
   - **Map to RST:** Developer/Localization.rst
   - **Files:** `*.xlf` (XLIFF format)
   - **Note:** Extract labels for API documentation context

2. **Resources/Private/Templates/** (Weight: MEDIUM)
   - **Documentation Priority:** MEDIUM
   - **Extract:** Template structure (for developer reference)
   - **Map to RST:** Developer/Templating.rst
   - **Files:** `[ControllerName]/[ActionName].html`
   - **Note:** Document template variables and ViewHelpers used

3. **Resources/Private/Layouts/** (Weight: LOW-MEDIUM)
   - **Documentation Priority:** LOW
   - **Extract:** Layout structure
   - **Files:** `*.html`

4. **Resources/Private/Partials/** (Weight: LOW-MEDIUM)
   - **Documentation Priority:** LOW
   - **Extract:** Reusable template fragments
   - **Files:** `*.html`

5. **Resources/Public/** (Weight: LOW)
   - **Documentation Priority:** LOW
   - **Extract:** Public asset information (if relevant)
   - **Subdirs:** `CSS/`, `JavaScript/`, `Icons/`, `Images/`
   - **Note:** Usually not documented in detail

### Documentation/ (Weight: CRITICAL)

**Purpose:** Official RST documentation

**Required Files:**
- `Index.rst` - Main entry point
- `guides.xml` - Build configuration (modern, preferred)
- `Settings.cfg` - Build configuration (legacy, if guides.xml not present)

**Common Structure:**
- `Introduction/` - Overview, features, screenshots
- `Installation/` - Installation and upgrade
- `Configuration/` - TypoScript, extension settings
- `Integration/` - Integration with other extensions
- `Editor/` - User guide for editors
- `Developer/` - Developer documentation
- `API/` - PHP API reference
- `Troubleshooting/` - Common issues

**Priority:** CRITICAL - This is the primary output target for extraction

### Tests/ (Weight: LOW)

**Purpose:** Unit, functional, and acceptance tests

**Documentation Priority:** LOW
- Extract test class names for coverage documentation
- Generally not documented in user-facing docs
- May reference in Developer/Testing.rst if test examples provided

**Structure:**
- `Tests/Unit/` - Unit tests
- `Tests/Functional/` - Functional tests
- `Tests/Acceptance/` - Acceptance tests (Codeception)

## Extraction Weight Matrix

### Primary Sources (Extract First)

```
Priority 1 - CRITICAL (Must Document):
ā”œā”€ ext_emconf.php → Extension metadata
ā”œā”€ ext_conf_template.txt → User configuration
ā”œā”€ composer.json → Dependencies
└─ Configuration/TCA/*.php → Data model

Priority 2 - HIGH (Should Document):
ā”œā”€ Classes/Controller/ → Controllers/Actions
ā”œā”€ Classes/Domain/Model/ → Domain entities
ā”œā”€ Classes/Service/ → Business logic
ā”œā”€ Configuration/TypoScript/ → TypoScript config
ā”œā”€ Configuration/Sets/ → Site sets (v13+)
└─ ext_localconf.php → Runtime registration

Priority 3 - MEDIUM (Consider Documenting):
ā”œā”€ Classes/Domain/Repository/ → Data access
ā”œā”€ Classes/ViewHelpers/ → Custom ViewHelpers
ā”œā”€ Configuration/Backend/ → Backend modules
ā”œā”€ Configuration/TsConfig/ → TSconfig
ā”œā”€ Configuration/Services.yaml → DI/Events
└─ Resources/Private/Language/ → Translation context
```

### Secondary Sources (Extract If Needed)

```
Priority 4 - MEDIUM-LOW:
ā”œā”€ Classes/Utility/ → Utility functions
ā”œā”€ ext_tables.php → Backend config
ā”œā”€ ext_tables.sql → Database schema
└─ Configuration/TCA/Overrides/ → Core extensions

Priority 5 - LOW:
ā”œā”€ Resources/Private/Templates/ → Template structure
ā”œā”€ Resources/Public/ → Public assets
ā”œā”€ Tests/ → Test coverage
└─ Configuration/Icons.php → Icon registry
```

## Documentation Mapping Strategy

### Extension Metadata → Introduction

**Source:** `ext_emconf.php`, `composer.json`, `README.md`

**Target:** `Documentation/Introduction/Index.rst`

**Extract:**
- Extension title → Main heading
- Description → First paragraph
- Version → Version marker
- Author → Credits section
- Constraints → Requirements section

**Example Mapping:**
```
ext_emconf.php:
  'title' => 'CKEditor Image Support'
  'version' => '13.1.0'
  'constraints' => ['typo3' => '12.4-13.5']

→ Introduction/Index.rst:
  ========================
  CKEditor Image Support
  ========================

  :Version: 13.1.0
  :Language: en

  Requirements
  ------------
  - TYPO3: 12.4 - 13.5
```

### Configuration Options → Integration/Configuration

**Source:** `ext_conf_template.txt`

**Target:** `Documentation/Integration/Configuration.rst`

**Extract Pattern:**
```
# cat=category; type=boolean; label=Label: Description
settingName = defaultValue

→ .. confval:: settingName
     :type: boolean
     :Default: defaultValue
     :Path: $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['ext_key']['settingName']

     Description text here
```

**Security Warnings:** Extract and map to `.. warning::` directive

### PHP Classes → API Documentation

**Source:** `Classes/**/*.php`

**Target:** `Documentation/API/[ClassName].rst`

**Mapping by Type:**

**Controllers:**
```php
Classes/Controller/UserController.php

→ API/UserController.rst

  .. php:class:: UserController

     User management controller

     .. php:method:: listAction(): ResponseInterface
```

**Models:**
```php
Classes/Domain/Model/User.php

→ API/User.rst

  .. php:class:: User

     User domain model

     .. php:attr:: username
        :type: string
```

**Repositories:**
```php
Classes/Domain/Repository/UserRepository.php

→ API/UserRepository.rst

  .. php:class:: UserRepository

     User data repository

     .. php:method:: findByEmail(string $email): ?User
```

### TCA Configuration → Developer/DataModel

**Source:** `Configuration/TCA/*.php`

**Target:** `Documentation/Developer/DataModel.rst`

**Extract:**
- Table name → Section heading
- ctrl['title'] → Table title
- columns → Field documentation

**Example:**
```php
Configuration/TCA/tx_myext_domain_model_user.php:
  'ctrl' => ['title' => 'User']
  'columns' => [
    'username' => [...],
    'email' => [...]
  ]

→ Developer/DataModel.rst:

  Users Table
  ===========

  Database table: tx_myext_domain_model_user

  Fields
  ------

  username
    User login name

  email
    User email address
```

### TypoScript → Configuration/TypoScript

**Source:** `Configuration/TypoScript/*.typoscript`

**Target:** `Documentation/Configuration/TypoScript.rst`

**Extract:**
- Constants → Configuration reference
- Setup → Implementation examples

## Quality Weighting Algorithm

### Documentation Coverage Score

```
Score = (P1_documented / P1_total) * 0.5 +
        (P2_documented / P2_total) * 0.3 +
        (P3_documented / P3_total) * 0.15 +
        (P4_documented / P4_total) * 0.05

Where:
  P1 = Priority 1 (CRITICAL) items
  P2 = Priority 2 (HIGH) items
  P3 = Priority 3 (MEDIUM) items
  P4 = Priority 4+ (LOW) items
```

### Gap Analysis Priority

```
Priority = BaseWeight * Severity * UserImpact

BaseWeight (from file structure):
  ext_conf_template.txt config = 10
  Controllers = 9
  Models = 9
  TCA = 8
  ext_emconf.php = 8
  Services = 7
  Repositories = 6
  ViewHelpers = 5
  Utilities = 4

Severity:
  Missing completely = 3
  Outdated (wrong defaults) = 2
  Incomplete (missing examples) = 1

UserImpact:
  User-facing (config, editor features) = 3
  Integrator-facing (TypoScript, TSconfig) = 2
  Developer-facing (API) = 1
```

### Example Calculation

```
Missing confval for "fetchExternalImages":
  Priority = 10 (ext_conf_template) * 3 (missing) * 3 (user-facing) = 90

Outdated Controller documentation:
  Priority = 9 (controller) * 2 (outdated) * 1 (developer) = 18

Missing Utility documentation:
  Priority = 4 (utility) * 3 (missing) * 1 (developer) = 12
```

**Action:** Document in priority order: 90 → 18 → 12

## Structure Checklist `[heuristic]`

What this skill expects before documenting an extension (upstream does not
mandate a fixed file set — see the Core API page for what each file does):

**Composer-Mode Installation:**
- āœ… `composer.json` with `"type": "typo3-cms-extension"`
- āœ… PSR-4 autoload configuration
- āœ… `Documentation/Index.rst`
- āœ… `Documentation/guides.xml` (modern) OR `Documentation/Settings.cfg` (legacy)

**Classic-Mode Installation:**
- āœ… `ext_emconf.php`
- āœ… `Documentation/Index.rst`
- āœ… `Documentation/guides.xml` (modern) OR `Documentation/Settings.cfg` (legacy)

### `ext_*` Files `[upstream]`

The reserved `ext_*` names and their meaning are defined by the Core API page
linked in the header (`ext_emconf.php`, `ext_localconf.php`, `ext_tables.php`
(deprecated), `ext_tables.sql`, `ext_tables_static+adt.sql`,
`ext_conf_template.txt`, `ext_typoscript_constants.typoscript`,
`ext_typoscript_setup.typoscript`). Upstream states no prohibition on other
`ext_*` file names — but an unknown `ext_*` file has no TYPO3 semantics, so
treat one as a smell worth documenting, not as forbidden.

## Best Practices for Extraction

1. **Follow Official Structure:** Extract based on official TYPO3 architecture
2. **Weight by Location:** Use file location to determine documentation priority
3. **Respect Conventions:** Map to RST sections based on TYPO3 conventions
4. **Security First:** Extract and highlight security warnings from configs
5. **Version Awareness:** Track version-specific features from ext_emconf.php
6. **Dependency Mapping:** Use composer.json and constraints for requirements
7. **Complete Coverage:** Prioritize user-facing config, controllers, models
8. **Context Awareness:** Understand file purpose from directory structure

## Resources

- **Official Structure:** https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/FileStructure/
- **TCA Reference:** https://docs.typo3.org/m/typo3/reference-tca/
- **TypoScript Reference:** https://docs.typo3.org/m/typo3/reference-typoscript/
- **Extbase/Fluid:** https://docs.typo3.org/m/typo3/book-extbasefluid/
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall