TYPO3 Documentation Skill
Create and maintain TYPO3 extension documentation per docs.typo3.org standards.
Core Workflow
No Documentation/ yet? Run this, do not type the file out. The
namespace is the part that comes out wrong when it is written from memory
-- guides.phpdoc.org and guides.typo3.org are both addresses nobody
serves -- and a file in the wrong namespace is well-formed XML that renders
nothing:
mkdir -p Documentation && cat > Documentation/guides.xml <<'XML'
<?xml version="1.0" encoding="UTF-8"?>
<guides xmlns="https://www.phpdoc.org/guides" links-are-relative="true">
<project title="TITLE" version="MAJOR.MINOR" release="MAJOR.MINOR.PATCH"/>
</guides>
XML
grep -Fc 'xmlns="https://www.phpdoc.org/guides"' Documentation/guides.xml
Settings.cfg is the file guides.xml replaced. Nothing reads it any
more, so writing one leaves the extension with no rendered documentation
and no error to show for it.
The grep prints 1 when the namespace is right and 0 when it is not.
Then replace TITLE and both versions. <project> carries them as
attributes; an element whose text is the extension key has no title and
no release. assets/guides.xml.dist holds the full file -- extension
element, interlinks, build configuration -- and is the better starting
point wherever the skill directory is reachable.
Run extraction first to find gaps:
scripts/extract-all.sh /path/to/extension
scripts/analyze-docs.sh /path/to/extension
Consult the matching reference
Use TYPO3 directives, not plain text
Validate: scripts/validate_docs.sh /path/to/extension
Render: scripts/render_docs.sh /path/to/extension
Critical: For "show docs", render HTML, not raw RST.
Element Selection Guide
| Content Type |
Directive |
| Complete code |
literalinclude (preferred) |
| Short snippets |
code-block with :caption: |
| Config options |
confval with :type:, :default: |
| PHP API |
php:method:: -- :returntype: for nullable/union |
| Notices |
note, tip, warning, important |
| Feature grids |
card-grid with footer stretched-link |
| Alternatives |
tabs (synchronized) |
| Screenshots |
figure with :zoom: lightbox + border/shadow classes |
Critical Rules
Official docs are canonical; on conflict the live manual wins -- report
drift (references/canonical-sources.md).
Upstream:
- UTF-8, 4-space indent (no tabs), LF; wrap at 80 chars where possible
- CamelCase files, sentence case headings
- Permalink anchors (
.. _label:) before every heading
- Index.rst in every subdirectory
- PNG/AVIF images with
:alt:
- PHP domain: no
?Type/Type|null in php:method::; use :returntype:
NR policy: no mailto: (upstream allows it; spam/PII -- use
Issues/Discussions); .editorconfig in Documentation/.
Heuristic: ~250 lines per RST, split with toctree; screenshots where
they help (backend modules, config, workflows).
Code Example Validation
Cross-reference examples against source: grep method names in
Classes/, compare CLI arguments with configure().
See references/extraction-patterns.md.
Pre-Commit Checklist
- Code blocks have
:caption:, inline code uses proper roles
- Screenshots exist with
:alt: and :zoom: lightbox
scripts/validate_docs.sh passes, render has no warnings
- README and Documentation/ synchronized
References
references/canonical-sources.md -- topic-to-upstream map, provenance labels
references/file-structure.md -- layout, naming
references/guides-xml.md -- the guides.xml skeleton, build config, interlinks
references/coding-guidelines.md -- CGL deltas, .editorconfig
references/rst-syntax.md -- headings, punctuation pitfalls
references/text-roles-inline-code.md -- :php:, :guilabel:, :ref:
references/code-structure-elements.md -- code blocks, confval, PHP domain
references/typo3-directives.md -- confval, versionadded, deprecated
references/content-directives.md -- accordion, tabs, card-grid
references/screenshots.md -- figures, image rules, SVG diagrams
references/rendering.md -- Docker commands, live preview
references/intercept-deployment.md -- webhook, build triggers
references/asset-templates-guide.md -- templates, screenshot workflow
references/architecture-decision-records.md -- ADR patterns
references/documentation-coverage-analysis.md -- coverage scoring
references/scripts-guide.md -- script options
references/typo3-extension-architecture.md -- extension layout
references/upstream-docs-contribution.md -- upstream docs PRs
references/render-guides-development.md -- changing the renderer itself: directive options, interlink parsing, integration-fixture semantics
1---2name: typo3-docs3description: "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+)."4license: "(MIT AND CC-BY-SA-4.0). See LICENSE-MIT and LICENSE-CC-BY-SA-4.0"5compatibility: "Requires php, docker (for rendering). A TYPO3 extension; Documentation/ may be absent."6metadata:7 source: https://skillmd.com/skills/netresearch/typo3-docs8 author: Netresearch DTT GmbH9 version: "2.20.2"10 repository: https://github.com/netresearch/typo3-docs-skill11allowed-tools: Bash(php:*) Bash(docker:*) Bash(sed:*) Bash(grep:*) Read Write Glob Grep12---1314# TYPO3 Documentation Skill1516Create and maintain TYPO3 extension documentation per docs.typo3.org standards.1718## Core Workflow19200. **No `Documentation/` yet?** Run this, do not type the file out. The21 namespace is the part that comes out wrong when it is written from memory22 -- `guides.phpdoc.org` and `guides.typo3.org` are both addresses nobody23 serves -- and a file in the wrong namespace is well-formed XML that renders24 nothing:2526 ```bash27 mkdir -p Documentation && cat > Documentation/guides.xml <<'XML'28 <?xml version="1.0" encoding="UTF-8"?>29 <guides xmlns="https://www.phpdoc.org/guides" links-are-relative="true">30 <project title="TITLE" version="MAJOR.MINOR" release="MAJOR.MINOR.PATCH"/>31 </guides>32 XML33 grep -Fc 'xmlns="https://www.phpdoc.org/guides"' Documentation/guides.xml34 ```3536 `Settings.cfg` is the file `guides.xml` replaced. Nothing reads it any37 more, so writing one leaves the extension with no rendered documentation38 and no error to show for it.3940 The `grep` prints `1` when the namespace is right and `0` when it is not.41 Then replace TITLE and both versions. `<project>` carries them **as42 attributes**; an element whose text is the extension key has no title and43 no release. `assets/guides.xml.dist` holds the full file -- extension44 element, interlinks, build configuration -- and is the better starting45 point wherever the skill directory is reachable.461. **Run extraction first** to find gaps:47 ```bash48 scripts/extract-all.sh /path/to/extension49 scripts/analyze-docs.sh /path/to/extension50 ```512. Consult the matching reference523. Use TYPO3 directives, not plain text534. Validate: `scripts/validate_docs.sh /path/to/extension`545. Render: `scripts/render_docs.sh /path/to/extension`5556> **Critical**: For "show docs", render HTML, not raw RST.5758## Element Selection Guide5960| Content Type | Directive |61|--------------|-----------|62| Complete code | `literalinclude` (preferred) |63| Short snippets | `code-block` with `:caption:` |64| Config options | `confval` with `:type:`, `:default:` |65| PHP API | `php:method::` -- `:returntype:` for nullable/union |66| Notices | `note`, `tip`, `warning`, `important` |67| Feature grids | `card-grid` with footer `stretched-link` |68| Alternatives | `tabs` (synchronized) |69| Screenshots | `figure` with `:zoom: lightbox` + border/shadow classes |7071## Critical Rules7273Official docs are canonical; on conflict the live manual wins -- report74drift (`references/canonical-sources.md`).7576Upstream:7778- **UTF-8**, **4-space** indent (no tabs), **LF**; wrap at **80 chars** where possible79- **CamelCase** files, **sentence case** headings80- **Permalink anchors** (`.. _label:`) before every heading81- **Index.rst** in every subdirectory82- **PNG/AVIF** images with `:alt:`83- **PHP domain**: no `?Type`/`Type|null` in `php:method::`; use `:returntype:`8485NR policy: **no `mailto:`** (upstream allows it; spam/PII -- use86Issues/Discussions); **.editorconfig** in `Documentation/`.8788Heuristic: **~250 lines** per RST, split with `toctree`; screenshots where89they help (backend modules, config, workflows).9091## Code Example Validation9293Cross-reference examples against source: grep method names in94`Classes/`, compare CLI arguments with `configure()`.95See `references/extraction-patterns.md`.9697## Pre-Commit Checklist98991. Code blocks have `:caption:`, inline code uses proper roles1002. Screenshots exist with `:alt:` and `:zoom: lightbox`1013. `scripts/validate_docs.sh` passes, render has no warnings1024. README and Documentation/ synchronized103104## References105106- `references/canonical-sources.md` -- topic-to-upstream map, provenance labels107- `references/file-structure.md` -- layout, naming108- `references/guides-xml.md` -- the guides.xml skeleton, build config, interlinks109- `references/coding-guidelines.md` -- CGL deltas, .editorconfig110- `references/rst-syntax.md` -- headings, punctuation pitfalls111- `references/text-roles-inline-code.md` -- `:php:`, `:guilabel:`, `:ref:`112- `references/code-structure-elements.md` -- code blocks, confval, PHP domain113- `references/typo3-directives.md` -- confval, versionadded, deprecated114- `references/content-directives.md` -- accordion, tabs, card-grid115- `references/screenshots.md` -- figures, image rules, SVG diagrams116- `references/rendering.md` -- Docker commands, live preview117- `references/intercept-deployment.md` -- webhook, build triggers118- `references/asset-templates-guide.md` -- templates, screenshot workflow119- `references/architecture-decision-records.md` -- ADR patterns120- `references/documentation-coverage-analysis.md` -- coverage scoring121- `references/scripts-guide.md` -- script options122- `references/typo3-extension-architecture.md` -- extension layout123- `references/upstream-docs-contribution.md` -- upstream docs PRs124- `references/render-guides-development.md` -- changing the renderer itself: directive options, interlink parsing, integration-fixture semantics