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/code-structure-elements.md

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

# Code Blocks and Structure Elements

Code-presentation elements for TYPO3 docs — routing, decision guides and the
skill's own snippet conventions. Syntax lives upstream (canonical, wins on
conflict — see `canonical-sources.md`):
[Code blocks](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Code/Codeblocks.html),
[Inline code](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Code/InlineCode.html),
[Confval](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Code/Confval.html),
[PHP domain](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Code/Phpdomain.html),
[Site settings](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Code/SiteSettings.html)
`[upstream]`.

## When to Use What

| Content Type | Element | Example |
|--------------|---------|---------|
| Short inline examples (< 5 lines) | `code-block` directive | Quick syntax demos |
| **Complete code snippets** | **`literalinclude` directive (preferred)** | PHP classes, services, TCA |
| External code files | `literalinclude` directive | Full example files |
| Configuration options | `confval` directive | Extension settings, TCA fields |
| Inline PHP | `:php:` role | Class names, method calls |
| Inline TypoScript | `:typoscript:` role | TypoScript properties |
| File paths | `:file:` role | `ext_localconf.php` |
| UI elements | `:guilabel:` role | Button labels, menu items |
| Keyboard shortcuts | `:kbd:` role | `Ctrl+S` |
| PHP API documentation | `php:class`, `php:method` | Public API reference |
| Site settings | `typo3:site-set-settings` | Site set configuration |

## Code Blocks

Directive syntax, options (`caption`, `linenos`, `lineno-start`,
`emphasize-lines`, `name`), ~200 language identifiers and the placeholder
convention: [Code blocks](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Code/Codeblocks.html)
`[upstream]`. Indent code-block content 4 spaces (CGL).

## literalinclude Directive (Preferred for Code)

`[NR policy]` The "preferred over code-block" grading is a house rule —
upstream mentions `literalinclude` without stating a preference. Rationale:
included files are testable and lintable, embedded blocks are not.

`[regression]` Verify any literalinclude option against the **renderer**
source before using or documenting it (typo3-docs-theme
`LiteralincludeDirective`, phpDocumentor guides option mapper) — the
renderer implements only a subset of Sphinx. Line-selection options
(`:lines:`, `:start-after:`, `:end-before:`) do not exist and are silently
ignored (checkpoint TD-51; upstream precedent #490 / render-guides#974).

**`literalinclude` is the preferred way to include code examples** in TYPO3 documentation. It provides:

- **Syntax validation**: IDE support catches errors in source files
- **Reusability**: Same snippet can be included in multiple places
- **Maintainability**: Update code in one place, documentation stays in sync
- **Testability**: Code files can be validated/linted separately

### File Naming Convention

Code snippet files use an **underscore prefix** to indicate they are include files:

| File Type | Naming Pattern | Example |
|-----------|----------------|---------|
| PHP classes | `_ClassName.php` | `_TranslationService.php` |
| Configuration | `_config-name.yaml` | `_services.yaml` |
| TCA | `_tca-tablename.php` | `_tca-apiendpoint.php` |
| TypoScript | `_setup.typoscript` | `_setup.typoscript` |

### File Organization

Store code snippets in the same directory as the RST file that uses them, or in a shared location:

```
Documentation/
├── Usage/
│   ├── Index.rst
│   ├── ApiEndpointExample.rst
│   ├── _ApiEndpoint.php           ← DTO class
│   ├── _ApiClientService.php      ← Service class
│   └── _tca-apiendpoint.php       ← TCA definition
├── Developer/
│   ├── Adr/
│   │   ├── ADR-009-ExtensionConfig.rst
│   │   ├── _TranslationService.php
│   │   └── _DirectUsage.php
```

### Syntax, Options, confval-menu

[Confval](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Code/Confval.html)
`[upstream]` — reserved attributes `:type:`, `:default:`, `:required:`,
`:name:`, `:class:`, `noindex` (free-form attributes render as written), and
`confval-menu` with `:display:`, `:name:`, `:exclude:`, `:exclude-noindex:`,
`:class:`.

## PHP Domain

Directives and cross-reference roles:
[PHP domain](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Code/Phpdomain.html)
`[upstream]`; the signature-parser limit (the RETURN type, not the parameters) in
[`typo3-directives.md`](typo3-directives.md#php-domain).

### When NOT to Use PHP Domain

Use `confval` instead of PHP domain for:
- TCA configuration
- Extension configuration arrays
- Any PHP array-based configuration

## Site Settings Documentation

[Site settings](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Code/SiteSettings.html)
`[upstream]` — incl. the `:Label: max=30` / `:default: max=10` syntax and
`PROJECT:` usage that an excerpt would lose.

## Decision Guide

### Use `literalinclude` When (Preferred)

- **Complete code examples** (classes, services, configuration)
- Code is **5+ lines** or represents a complete unit
- Code should be **syntactically valid** and testable
- Same code might be **referenced multiple times**
- You want **IDE support** for the source files

### Use `code-block` When

- Very short snippets (< 5 lines)
- Pseudocode or conceptual examples
- Code with intentional placeholders like `<your-value>`
- Quick syntax demonstrations

### Use `confval` When

- Documenting configuration options
- Values have type, default, required attributes
- Need structured presentation of settings

### Use Inline Roles When

- Mentioning code elements in text
- Referencing file paths, UI elements
- Keep paragraphs readable (avoid overuse)

### Use PHP Domain When

- Documenting public API
- Creating formal class/method reference
- Need cross-referencing between API elements

## Pre-Commit Checklist

1. ✅ **Complete code examples use `literalinclude`** with `_filename.ext` source files
2. ✅ Source files have underscore prefix (`_MyClass.php`)
3. ✅ All code blocks/includes have `:caption:` with target file path
4. ✅ Correct `:language:` identifier used
5. ✅ Code syntax is valid (highlighting works)
6. ✅ Placeholders use angle brackets `<your-value>`
7. ✅ Configuration uses `confval` directive
8. ✅ Inline code uses appropriate roles (`:php:`, `:file:`, etc.)
9. ✅ UI elements use `:guilabel:`

## References

- **Code Blocks:** https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Code/Codeblocks.html
- **confval:** https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Code/Confval.html
- **Inline Code:** https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Code/InlineCode.html
- **PHP Domain:** https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Code/Phpdomain.html
- **Site Settings:** https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Code/SiteSettings.html
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