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/render-guides-development.md

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

# Developing render-guides itself

For changing the renderer — `TYPO3-Documentation/render-guides`, the
`typo3-docs-theme` package and its integration fixtures — not for writing
documentation with it. Everything here was measured against the repository
rather than taken from its documentation, which does not describe any of the
parsing or fixture behaviour below. The one overlap is the committed stylesheet:
`references/screenshots.md` already notes that it is a build artifact that must
be rebuilt in the same commit — the section here adds what CI checks about it.
render-guides' own `AGENTS.md` (in the root of
`TYPO3-Documentation/render-guides`, not this skill's) covers its `make` targets, fixture recording
and layout; read it first.

## Directive options do not arrive as you wrote them

`Directive::getOptionString()` hides two shapes that reach the directive as
something other than the text in the `.rst` file. Both produce a value that
looks plausible and resolves to nonsense.

**An option written without a value is the boolean `true`.**
`DirectiveRule::parseDirectiveOption` matches `/^(\s+):(.+):(\s*)$/` and
constructs `new DirectiveOption($name, true)`; `getOptionString()` is `strval()`
over that, so `:changelog:` arrives as the string `"1"` and is happily treated
as an identifier. Read the option object instead and test the flag:

```php
if (!$directive->hasOption('changelog')) {
    return null;
}
$value = $directive->getOption('changelog')->getValue();   // string|true
$raw   = $value === true ? '' : (string) $value;
```

**A value on the following line is appended to that flag.**
`collectDirectiveOptionContent` calls `DirectiveOption::appendValue(' ' . trim($line))`,
which is `((string) $this->value) . $append` — so

```rst
..  versionchanged:: 14.0
    :changelog:
        feature-107628-1729026000
```

arrives as `"1 feature-107628-1729026000"`, and the `=== true` check above never
fires. `appendValue` always prepends one space and can run once per continuation
line, so the reliable tell is whitespace, not the `1`.

**Read the value untrimmed.** The inline form is trimmed by the parser and a
continued one is not, so leading whitespace is the only thing separating them.
Trim first and a trailing space after the option name silently decides whether a
value is accepted — a rendering difference caused by an invisible character.

**Check the encoding before any `/u` pattern.** `preg_match()` returns `false`,
not `0`, on malformed UTF-8, so `=== 1` reads a byte-damaged value as "no
match". Such a value reaching `SluggerAnchorNormalizer` throws in
`UnicodeString` and ends the entire render — no pages written, and the error
names the Twig template rather than the `.rst` file at fault.

## Interlink syntax in the theme is wider than upstream's

`vendor/package:anchor` parses only because `typo3-docs-theme.php` rebinds
`InterlinkParser::class` to `ExtendedInterlinkParser`, whose domain pattern is
`[a-zA-Z0-9\-_\/.]+`. Upstream's `DefaultInterlinkParser` uses
`[a-zA-Z0-9-_]+` and rejects the `/`. Anything splitting `<domain>:<anchor>` by
hand drifts from `:ref:`, `:doc:` and `ApiClassTextRole`, which all go through
the bound parser — delegate instead of writing another `explode(':')`.

## What the integration suite actually asserts

`tests/Integration/IntegrationTest.php` compares far less than the fixture files
suggest, and the gaps are silent.

| Fixture location | HTML comparison |
|---|---|
| `tests/Integration/tests/` | only between `<!-- content start -->` and `<!-- content end -->` |
| `tests/Integration/tests-full/` | the whole file |

Everything outside those markers — head, navigation, footer — is never compared,
so it can be arbitrarily wrong in an expected file.

**Log files are compared by line containment, not equality**
(`assertFileContainsLines`). Three consequences, each verified by mutation:
an added warning is invisible; a duplicate expected line asserts nothing beyond
the first; and an expected log of a single blank line asserts nothing at all,
because `explode("\n", …)` yields `['']` and every string contains the empty
string.

**The strong assertion is an absent `expected/logs/` directory.** Where a
fixture ships no expected log, the runner asserts that no warning log was
written — the only place in the suite a new warning cannot hide. The suite
does not use the network: answers from docs.typo3.org, api.typo3.org and
Packagist come from recordings in `tests/Integration/http-fixtures/`, and an
address without a recording is answered as not found. A fixture that adds an
interlink, a PHP class or a Composer package needs its recordings (record with
`RECORD_HTTP=1`, as render-guides' `AGENTS.md` describes); without them the
lookup is answered as not found.

**Regenerate expectations, do not hand-edit them.** Each fixture renders into
its own `temp/`; splice the marker region from there into `expected/`. And when
counting fixtures, exclude `temp/` — it is generated output that looks exactly
like an expectation to a recursive grep.

## The committed theme assets are gated by a byte comparison

`packages/typo3-docs-theme/resources/public/` (compiled `css/theme.css`,
`js/theme.min.js`) is committed. `.github/workflows/check-built-assets.yaml`
runs `npm ci --ignore-scripts && npm run build` in `packages/typo3-docs-theme`
whenever a pull request or merge-queue entry touches that package, and on
every push to `main`, and fails when `assets/` or `resources/public/` then differ from the
commit, or contain untracked files. A SCSS or JS change without its rebuilt
output is therefore red, not silently shipped.

Rebuild with `npm ci && npm run build` in `packages/typo3-docs-theme` and
commit `assets` and `resources/public` together with the source change. The
check uses the Node version from that package's `.nvmrc`; a different local
Node can produce a different byte stream, so confirm first that a no-op
rebuild on `main` leaves the tree unchanged.

## Updating Composer dependencies

- **Raising the PHP floor** (`require.php` and `config.platform.php` in the
  root `composer.json`) is a full `composer update`: the whole tree may resolve
  differently once the platform changes.
- **Upgrading one library** is a targeted update with its dependencies,
  `composer update <vendor/pkg> [<vendor/pkg> …] -W`, so unrelated upgrades
  stay out of the change.
- **`composer update --lock` alone** only refreshes the lock file's content
  hash; it updates no package, so it is not enough after changing the platform
  or a constraint.
- **A dependency bump can change fixture output.** A newer
  `phpdocumentor/guides` changes rendered HTML (1.9.2 → 1.9.6 started wrapping
  admonition bodies in `<p>`, rendered one-line `.. hint::` text and passed the
  code-block language to the highlighter). Regenerate the expectations and
  consider a separate pull request for the bump, so the fixture diff is not
  mixed with your change.
- **`composer.lock` conflicts on rebase.** During a rebase, `--ours` is the
  branch you rebase onto and `--theirs` is your replayed commit. Take upstream's
  lock (`git checkout --ours composer.lock`), re-run the same
  `composer update` command your commit made (full or targeted), `git add composer.lock`, continue, and run
  `composer install` before the tests — `vendor/` is stale after the rebase.
- **PHP extensions per package.** Each sub-package declares the `ext-*` its
  own source uses in its `composer.json` (at `a0e64940`: `typo3-docs-theme`
  curl and dom; `typo3-guides-cli` dom, libxml and simplexml;
  `typo3-version-handling` curl). Code that starts calling another extension's
  functions adds the declaration to that package.

## Contributing to TYPO3-Documentation repositories

- **Commit messages** follow the How to Document rules
  ([Commit messages](https://docs.typo3.org/permalink/h2document:commit-messages)),
  which render-guides' `AGENTS.md` repeats: a `[TASK]` / `[BUGFIX]` /
  `[FEATURE]` summary (render-guides adds `[DOCS]`), a body that explains why,
  then `Assisted-by: <tool/model name> <contact>` when AI helped beyond a
  spelling check, before the human's `Signed-off-by:`. `Co-authored-by:` is for
  people (and dependabot), never for a model.
- **No other agent trailers.** Session or host metadata trailers and a session
  footer in the pull request body are not part of those rules; maintainers
  squash-merge without them. Where a personal convention adds such trailers,
  the repository rule wins: drop them here.
- **Architecture decisions** of the organisation live in
  `TYPO3-Documentation/.github` under `Documentation/Decisions/ADR-NNN-Name.rst`:
  reStructuredText starting with `.. include:: /Includes.rst.txt`, sections
  Status, Context, Decision, Alternatives Considered, Consequences. Contributors
  without push access open the pull request from a fork.
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