---
title: "Documentation"
manual: "Headless Content Blocks"
version: "main"
permalink: "https://docs.typo3.org/permalink/netzbewegung/nb-headless-content-blocks:documentation@main"
source: "Index.rst"
start: true
rendered: "2026-09-22T00:10:27+00:00"
---

# Documentation {#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](https://github.com/Netzbewegung-Backend/nb_headless_content_blocks) whether the extension fits your setup. The same documentation is rendered on [docs.typo3.org](https://docs.typo3.org/p/netzbewegung/nb-headless-content-blocks/main/en-us/).

## Getting started {#getting-started}

-   [Getting started](https://docs.typo3.org/permalink/netzbewegung/nb-headless-content-blocks:getting-started@main) — install the extension, include the Site Set, and verify your first JSON response

## Concepts (why it works this way) {#concepts-why-it-works-this-way}

-   [Architecture](https://docs.typo3.org/permalink/netzbewegung/nb-headless-content-blocks:architecture@main) — the normalization pipeline from Content Block record to JSON: DataProcessor, `RecordArrayBuilder`, normalizers, field value transformers, and the extension points

## How-to guides (solve a task) {#how-to-guides-solve-a-task}

-   [Define image variants](https://docs.typo3.org/permalink/netzbewegung/nb-headless-content-blocks:define-image-variants@main) — responsive thumbnails per field via `headless.yaml`, with per-site TypoScript overrides
-   [Migrate legacy thumbnails](https://docs.typo3.org/permalink/netzbewegung/nb-headless-content-blocks:migrate-legacy-thumbnails-to-headless-yaml@main) — replace the old `headless.php` thumbnail generators
-   [Post-process JSON with headless.php](https://docs.typo3.org/permalink/netzbewegung/nb-headless-content-blocks:post-process-json-with-headless-php@main)
-   [Add sub data processors](https://docs.typo3.org/permalink/netzbewegung/nb-headless-content-blocks:add-sub-data-processors@main) — menus, record lists and other TypoScript data inside a block's `data`
-   [Render containers](https://docs.typo3.org/permalink/netzbewegung/nb-headless-content-blocks:render-containers@main) — EXT:container columns via the `nb-container-json` processor
-   [Register a custom normalizer](https://docs.typo3.org/permalink/netzbewegung/nb-headless-content-blocks:register-a-custom-normalizer@main) — own value types in the JSON output
-   [Register a field value transformer](https://docs.typo3.org/permalink/netzbewegung/nb-headless-content-blocks:register-a-field-value-transformer@main) — own string field shaping (like password blanking)
-   [Modify fields with the PSR-14 event](https://docs.typo3.org/permalink/netzbewegung/nb-headless-content-blocks:modify-fields-with-the-psr-14-event@main) (deprecated — prefer normalizers/transformers)

## Reference (look it up) {#reference-look-it-up}

-   [JSON contract](https://docs.typo3.org/permalink/netzbewegung/nb-headless-content-blocks:json-contract@main) — the exact output shape per field type, frozen by characterization tests
-   [Normalizers and transformers](https://docs.typo3.org/permalink/netzbewegung/nb-headless-content-blocks:normalizers-and-transformers@main) — built-in services, interfaces and DI tags
-   [Processor options](https://docs.typo3.org/permalink/netzbewegung/nb-headless-content-blocks:processor-options@main) — TypoScript options of `nb-content-blocks-json` and `nb-container-json`

## Troubleshooting {#troubleshooting}

-   [Troubleshooting](https://docs.typo3.org/permalink/netzbewegung/nb-headless-content-blocks:troubleshooting@main) — symptom → cause → fix
-   [Testing troubleshooting](https://docs.typo3.org/permalink/netzbewegung/nb-headless-content-blocks:testing-troubleshooting@main) — symptom → cause → fix for the extension's own test setup (contributors)

## Design records (internal) {#design-records-internal}

`Design/` holds planning and analysis records — where wording differs from the code, the code wins. Notable: [Improve ToArray design record](https://docs.typo3.org/permalink/netzbewegung/nb-headless-content-blocks:design-improve-rewrite-the-toarray-conversion@main) — the 2026-08 rewrite of the ToArray conversion (normalizer registry, Schema API migration, declarative image variants) with its decisions and rationale.

## Archive (internal) {#archive-internal}

[\_archive/](https://docs.typo3.org/permalink/netzbewegung/nb-headless-content-blocks:archive@main) holds superseded documentation — how the extension got here, not how it works today. Notable: [legacy thumbnails via headless.php](https://docs.typo3.org/permalink/netzbewegung/nb-headless-content-blocks:legacy-thumbnails-via-headless-php-imageviewhelper@main) — the `ImageViewHelper` pattern that declarative image variants replaced.