netresearch/typo3-docs-skill / skills/typo3-docs
typo3-docs
FlaggedUse 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+).
references/upstream-docs-contribution.md
View on GitHub<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
<!-- SPDX-FileCopyrightText: Netresearch DTT GmbH -->
# Contributing to TYPO3-Documentation Repositories
`[regression]`/process knowledge — conventions and verification techniques
for PRs against official TYPO3 documentation repositories
(`TYPO3-Documentation/*`, e.g. `TYPO3CMS-Reference-CoreApi`), and for
fact-checking documentation claims against the TYPO3 core. **The target
repository's own `AGENTS.md` outranks this page** — see the first bullet
below. Upstream prose that binds every one of these repos:
Howto/Contribute (edit-on-GitHub vs local Docker, approval requirement) and
[Advanced/CommitMessages](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Advanced/CommitMessages.html),
which defines the commit trailers including `Releases:`. The squash-only and
render-gate facts below are observed working knowledge on top of them.
## Verify claims against core source, not rendered HTML
When a documentation statement must be checked against actual core behavior
("function X throws", "context Y provides variable Z"), fetch the **raw
source** — scraping docs.typo3.org HTML fights the theme markup (modals,
`data-*` attributes, code buttons) and burns several grep attempts for one
sentence of content:
```bash
# Core class source (any branch: main, 13.4, 12.4, ...)
curl -s https://raw.githubusercontent.com/TYPO3/typo3/main/typo3/sysext/core/Classes/Site/Entity/Site.php
# Changelog RST source — the authoritative wording of a Breaking/Deprecation
curl -s https://raw.githubusercontent.com/TYPO3/typo3/main/typo3/sysext/core/Documentation/Changelog/13.0/Breaking-100963-DeprecatedFunctionalityRemoved.rst
```
Changelog files live under
`typo3/sysext/core/Documentation/Changelog/<version>/<Type>-<issue>-<Title>.rst`.
To confirm behavior differences between LTS versions, fetch the same class
from both branch refs and diff.
**Changelog permalinks** (`https://docs.typo3.org/permalink/changelog:...`)
can be verified without rendering: a HEAD request answers `307` with a
`Location` naming the resolved page; anything else means the anchor is wrong.
## PR conventions in TYPO3-Documentation repos
- **Squash-only merges.** The repos allow only squash; separate commits (and
preserved authorship of commits taken over from another PR) survive only as
`Co-authored-by:` trailers in the squash commit. Rebasing keeps authors in
the branch history, but a merge never transplants them to the target branch.
- **Read the repository's `AGENTS.md` before the first commit — it owns
trailers and backport scope, and it is more specific than anything here.**
`TYPO3CMS-Reference-CoreApi` has carried one since 2026-08-21 (its
`CLAUDE.md` is the single line `@AGENTS.md`), and it fixes what this page
used to get wrong: `Releases:` in *every* commit whatever your label
permissions, the trailer order (`Resolves:`/`References:`, `Releases:`,
`Assisted-by:`, `Signed-off-by:`), `Assisted-by:` in the
`<model> <contact>` form, the default `main, 14.3` with `13.4` reserved for
a bugfix or security fix worth backporting that far — *not* for plain
content or style changes — the `main only` and `changelog` labels, and how
to verify the backport bot's PRs actually landed. Do not restate those
rules from memory and do not ask a maintainer which labels apply: the
trailer is the channel they read. (2026-08-13, CoreApi #6651: a PR body carrying
the free text `backport 13.4, backport 14.3` plus a comment asking for the
scope waited five weeks for an answer that was "use the trailer". The
`AGENTS.md` did not exist yet; it does now.)
- **The repo's rules reach a session only through its `CLAUDE.md` import,
and even then do not carry on their own — re-read your trailers before you
push.** Measured 2026-09-18, Haiku 4.5 in headless
`claude -p` sessions against a clone with one uncommitted one-sentence
edit, asked only for the commit message. **What reaches the session is the
`CLAUDE.md` holding `@AGENTS.md`, not the `AGENTS.md` itself**: delete that
one-line `CLAUDE.md` and leave `AGENTS.md` in place, and `Releases:`, the
TYPO3 prefix and every trailer drop to 0 of 6 — indistinguishable from
deleting `AGENTS.md` too (0 of 4), pooling to 0 of 10 against 6 of 10 with
the import. A `CLAUDE.md` symlinked to `AGENTS.md` works but is no better
(`Releases:` 2 of 6 against the import's 3 of 6, within noise) and a
Windows clone without `core.symlinks` turns it into a text file whose
content is the string `AGENTS.md`. With the import and nothing else,
`Releases:` appeared in 6 of 10 runs, the `main, 14.3` default in 4 of 10, the
prescribed trailer order complete in 4 of 10, and every trailer in the
repo's own form in 2 of 10: a personal `AGENT_NAME:MODEL_VERSION`
convention in a user-level `CLAUDE.md` usually wins that field. With the
two bullets above also in context — the state this reference creates — the
same setup gave `Releases: main, 14.3` and the full order in 6 of 6, and
the repo's `Assisted-by:` form in 3 of 6. That is why this bullet exists as
a pointer rather than being left to the repository alone. Where the two
disagree, the repo wins; check the message, do not assume.
- **The `render / Test documentation` CI job is the authoritative render
gate** — equivalent to a local `render-guides --fail-on-log` run; a green
job is the evidence a "renders without warnings" claim needs.
- `[regression]` Member association does not imply triage rights: requesting reviewers or
setting labels may fail (`404` / GraphQL permission error) even for org
members. That is expected and needs no workaround: the `Releases:` trailer
above is the channel, so do not retry the API, do not @-mention a
maintainer to ask which labels apply.
## Find where a topic lives: query the manual's inventory
Do not guess rendered paths — every manual publishes its object inventory:
```bash
curl -s https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/objects.inv.json \
| jq -r '."std:label" | to_entries[] | select(.key|test("confval"; "i")) | "\(.key) -> \(.value[2])"'
```
`std:doc` maps document names, `std:label` maps every anchor to its page —
this is how a moved page or the right `:ref:` target is found in one call
(located the intersphinx section and the relocated InterlinkInventories page
this way, 2026-08-14). Works for any manual (render-guides, Core API, …) by
swapping the base URL.
**Keep the `"i"` flag.** Labels are lowercase, while the term you search for
usually comes from a page name or a class name and is not. Without the flag a
search is case-sensitive and answers nothing, which reads like "this topic has
no anchor": against the Core API inventory on 2026-09-19,
`test("SiteHandling")` matched 0 labels and `test("sitehandling")` matched 91.
## Check a permalink without rendering
A `HEAD` request resolves a permalink, so a `:ref:` target or an outbound link
can be verified before the review rather than in it. A valid anchor answers
`307` and names the page, a wrong one answers `404`:
```bash
curl -sI https://docs.typo3.org/permalink/t3coreapi:sitehandling-base-variants-functions \
| grep -Ei '^(HTTP|Location)'
```
Do not trim the headers with `head -2`. `docs.typo3.org` sends `Location:` on
line 6, so the first two lines are the status and `Server: nginx` — the
resolved page, which is the whole point of the check, never appears. The
`grep -Ei` form prints both lines and works with BSD grep and with a lowercase
header name. (Stefan Frömken, review on CoreApi #6992, 2026-09-18.)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 119k | Updated | Claude CodeCodex | Verified | Install |
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |