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/rst-syntax.md

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

# RST Syntax Reference

TYPO3-specific reStructuredText conventions. Generic RST/Sphinx syntax
(inline formatting, code-block basics, plain tables, admonitions, images,
toctree, comments, substitutions) is not repeated here — see
[`code-structure-elements.md`](code-structure-elements.md) for code blocks
and `literalinclude`, [`content-directives.md`](content-directives.md) for
tables, admonitions, and comments, [`screenshots.md`](screenshots.md) for
images, [`coding-guidelines.md`](coding-guidelines.md) for
indentation/whitespace, [`file-structure.md`](file-structure.md) for
toctree and substitutions, and [`typo3-directives.md`](typo3-directives.md)
for permalink anchors and intersphinx `:ref:` targets.

## Headings

Hierarchy (`=` over+under for the title, then `= - ~ " '` underlines),
sentence case and underline length:
[Headlines and sections](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Menus/HeadlinesAndSection.html)
and the [CGL](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/CodingGuidelines/Index.html)
`[upstream]`. Local deltas: underline-length notes in
[`coding-guidelines.md`](coding-guidelines.md#heading-hierarchy); permalink
anchors in [`typo3-directives.md`](typo3-directives.md#permalink-anchors-labels).

**No text roles in headlines** `[regression]`. Do not use `:rst:`, `:php:`,
`:typoscript:` or any other text role in a headline. Use plain inline code
with single backticks instead. Source: TYPO3 documentation team review,
"Avoid using language roles in headlines as they render strangely"
([TYPO3CMS-Guide-HowToDocument#571](https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument/pull/571#discussion_r4072925264)).

```rst
.. ❌ WRONG -- text role in a headline
Linking the changelog entry with :rst:`:changelog:`
===================================================

.. ✅ CORRECT -- plain inline code
Linking the changelog entry with `:changelog:`
==============================================
```

## Lists

RST bullet/numbered/definition list syntax is standard Sphinx
([Bullet lists](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Lists/BulletLists.html)).
One added rule — `[NR policy]`, not stated on any upstream list/CGL page:

**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

## README.md and Documentation/ Synchronization `[NR policy]`

Keep README.md and Documentation/ in sync to avoid contradictions.

**Content Parity:**
- Topics covered in README.md should have corresponding coverage in Documentation/.
- New features added to README.md should be documented in the appropriate .rst files.
- README.md serves as a quick-start; Documentation/ provides comprehensive details.

**Consistency (No Contradictions):**
When README.md and Documentation/ cover the same topics, they must not contradict each other:

- **CLI commands**: Command names and option flags must match.
  - ❌ README: `vault:master-key:rotate --new-key-file=...`
  - ✅ Docs: `vault:rotate-master-key --new-key=...`
  - Fix: Update README to match Documentation/.
- **Code examples**: TCA configs, API usage, class names must be consistent.
  - ❌ README: `'type' => 'user'`
  - ✅ Docs: `'type' => 'input'`
  - Fix: Update README to match Documentation/.
- **Configuration values**: Defaults and option names must align.

**Source of Truth:**
- Documentation/ is the authoritative source.
- When inconsistencies are found, update README.md to match Documentation/.
- Commit README.md and Documentation/ changes together atomically.

## Common Documentation Errors

Patterns of errors found during TYPO3 v13 extension documentation reviews. Check for these issues before publishing.

### Version Directive Accuracy

**Documenting the version you are currently building is correct** — write the
directive with the feature, so the documentation is ready when the release
lands. Stated by a docs-team maintainer while rejecting the opposite claim
([HowToDocument#544](https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument/pull/544)):
TYPO3 15.0 is documented with `versionadded:: 15.0` while 15.0 is being built.
The [Versions page](https://docs.typo3.org/permalink/h2document:versions)
documents the directives themselves and does not address the timing either way.

```rst
.. Correct -- the release this feature is going into
.. versionadded:: 1.3.0
   Added multi-site support.
```

The residual risk is only the *number*: the next release may turn out to be
`2.0.0` rather than `1.3.0`, and then the directive names a version that never
shipped. That happens rarely, it is detectable afterwards, and a stale number
is tolerable — so it is not worth withholding the directive until release day.

**Deliberately not enforced.** A check for this was written and then removed:
distinguishing a skipped number from a pending one needs the full tag history,
and three ordinary situations look identical to a skipped number — a shallow
clone or a `--no-tags` CI checkout (the release is invisible, not missing), a
two-component number like `13.4` against a `13.4.0` tag, and a patch release
prepared on a maintenance line while a higher major already exists. Each of
those produced a warning against correct documentation, which is the harm the
old prohibition caused in the first place. For a defect this rare and this
cheap to live with, a gate that cries wolf is worse than no gate.

If a number does turn out wrong, correct it in the same commit that notices.

### ChangeLog Completeness

The ChangeLog section must include ALL released versions. Missing versions create gaps in the project history:

- Check git tags: `git tag --list --sort=-version:refname`
- Every tagged release must have a corresponding ChangeLog entry
- Entries must be in reverse chronological order (newest first)

### Language and Feature Count Claims

Numeric claims in documentation must be verifiable:

- **Language count:** "Supports N languages" must match the actual number of files in `Resources/Private/Language/`. Count with: `ls -1 Resources/Private/Language/*.xlf | wc -l`
- **Feature lists:** If documentation claims "5 CLI commands", verify with: `grep -rl 'extends Command' Classes/Command/ | wc -l`
- **Configuration option counts:** Verify against `ext_conf_template.txt` or TCA definitions

### Speculative Roadmap Content

Documentation for unreleased versions (e.g., 3.1.0, 3.2.0, 4.0.0 planned features) must be handled carefully:

- Remove speculative feature descriptions from published documentation entirely, OR
- Clearly mark roadmap content with an explicit admonition:

```rst
.. note::
   The following features are planned for future releases and are
   subject to change. They are not available in the current version.
```

This is about features nobody has built yet — not about the version number of a
feature that exists. A `versionadded` for the release you are building is
correct; see *Version Directive Accuracy* above.

### Unresolved TODO Directives

`[regression]` The renderer **silently drops** `.. todo::` content — readers
never see it, so a forgotten todo is invisible rather than embarrassing, and
nothing relies on it rendering (verified by live render; documented upstream
via TYPO3CMS-Guide-HowToDocument PR #542). Before release:

- Search for all TODOs: `grep -rn '.. todo::' Documentation/`
- Either resolve each TODO with actual content, or delete it
- For author-only notes use a plain `..` comment — never rely on todo as a
  visible marker

### TypoScript Documentation Accuracy

TypoScript examples must reflect actual file contents:

- **Backend modules** use `module.` prefix, not `plugin.`:
  ```typoscript
  # Correct for backend modules
  module.tx_myext {
      settings.itemsPerPage = 20
  }

  # Wrong -- plugin. prefix is for frontend plugins only
  plugin.tx_myext {
      settings.itemsPerPage = 20
  }
  ```
- Sub-key paths must match the actual TypoScript setup files in `Configuration/TypoScript/`
- Default values in documentation must match the values in the shipped `.typoscript` files

### Screenshot Placeholders

Screenshot sections must contain actual images or be clearly marked:

- Every `.. figure::` or `.. image::` directive must reference an existing file
- Validate with: `grep -rn '.. figure::\|.. image::' Documentation/ | while read line; do file=$(echo "$line" | grep -oP '(?<=:: ).*'); [ ! -f "$file" ] && echo "MISSING: $line"; done`
- If screenshots are not yet available, use a visible placeholder admonition instead of an empty or broken image reference:

```rst
.. note::
   Screenshot pending. This section will be updated with actual
   screenshots in a future revision.
```

- Never leave empty `Images/` directories or broken image references in published docs

## 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/

## Interlinks: inventories are auto-provided; prefer `:ref:` over raw permalink URLs

`[upstream]` for the auto-provided inventories:
[Interlink inventories](https://docs.typo3.org/permalink/t3renderguides:interlink-inventories)
("It is not necessary anymore to list each of the standard inventories in
the guides.xml"). The permalink smoke test below is `[regression]`.

- `guides.xml` only declares the repo's own `interlink-shortcode` — the standard inventories (`t3coreapi`, `t3viewhelper`, `t3tca`, …) are injected by the docs theme at build time, so `:ref:`t3viewhelper:…`` works without declaring them.
- Converting a raw `` `Title <https://docs.typo3.org/permalink/short:anchor>`_ `` link to `` :ref:`Title <short:anchor>` `` is safe AND build-validated (a typo fails the render); raw permalink URLs bypass build validation but can be smoke-tested (`curl -sL -o /dev/null -w "%{http_code}" https://docs.typo3.org/permalink/<short>:<anchor>` — real ones 200-redirect, bogus 404).
- **Title over/underline mismatch is NOT a render blocker** in the TYPO3 toolchain (phpdoc/guides is lenient where strict docutils errors; verified — a 39/33 mismatch rendered fine even under `--fail-on-log`). Fix it as a correctness/portability issue, don't call it a blocker without rendering.
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