Documentation
This page explains what the extension's documentation covers and where to find it. The docs are written for developers who build a headless TYPO3 frontend with EXT:headless and EXT:content_blocks — see the README whether the extension fits your setup. The same documentation is rendered on docs.typo3.org.
Getting started
- Getting started — install the extension, include the Site Set, and verify your first JSON response
Concepts (why it works this way)
- Architecture — the normalization pipeline from Content Block record to JSON: DataProcessor,
Record, normalizers, field value transformers, and the extension pointsArray Builder
How-to guides (solve a task)
- Define image variants — responsive thumbnails per field via
headless., with per-site TypoScript overridesyaml - Migrate legacy thumbnails — replace the old
headless.thumbnail generatorsphp - Post-process JSON with headless.php
- Add sub data processors — menus, record lists and other TypoScript data inside a block's
data - Render containers — EXT:container columns via the
nb-processorcontainer- json - Register a custom normalizer — own value types in the JSON output
- Register a field value transformer — own string field shaping (like password blanking)
- Modify fields with the PSR-14 event (deprecated — prefer normalizers/transformers)
Reference (look it up)
- JSON contract — the exact output shape per field type, frozen by characterization tests
- Normalizers and transformers — built-in services, interfaces and DI tags
- Processor options — TypoScript options of
nb-andcontent- blocks- json nb-container- json
Troubleshooting
- Troubleshooting — symptom → cause → fix
- Testing troubleshooting — symptom → cause → fix for the extension's own test setup (contributors)
Design records (internal)
Design/ holds planning and analysis records — where wording differs from the code, the code wins. Notable: Improve ToArray design record — the 2026-08 rewrite of the ToArray conversion (normalizer registry, Schema API migration, declarative image variants) with its decisions and rationale.
Archive (internal)
_archive/ holds superseded documentation — how the extension got here, not how it works today. Notable: legacy thumbnails via headless.php — the Image pattern that declarative image variants replaced.