Block-Themes mit theme.json: Templates, Parts und Child-Theme

Ein Block-Theme besteht im Kern aus HTML-Dateien mit Block-Markup und einer einzigen JSON-Datei. Um sein Verhalten zu verstehen, sind vor allem drei Fragen wichtig: Welches Template liefert WordPress für eine Anfrage aus? Warum hat eine geänderte Datei manchmal keine sichtbare Wirkung? Was geschieht mit den Einstellungen des Eltern-Themes, wenn ein Child-Theme eine eigene theme.json mitbringt? Das bestimmen einige Funktionen im Core.

Dieser Beitrag baut ein kleines, aber vollständiges Block-Theme mit style.css, theme.json, einem Template, zwei Template Parts, einem Pattern und einer Style Variation auf und setzt anschließend ein Child-Theme darauf. Dabei folgt er dem Quelltext von WordPress 7.1 und zeigt, wo der Site Editor Änderungen ablegt, in welcher Reihenfolge Templates aufgelöst werden und wie die Datenebenen der globalen Einstellungen und Stile zusammenfließen. Aktuell ist laut Versions-API von WordPress.org am 29.09.2026 die Version 7.1.2.

Die Dateien eines minimalen Block-Themes

Als Block-Theme gilt ein Theme, sobald WordPress eine lesbare Datei templates/index.html findet. WP_Theme::is_block_theme() prüft genau diesen Pfad und aus Kompatibilitätsgründen zusätzlich das ältere block-templates/index.html. Alles Weitere ist technisch optional, für ein brauchbares Theme aber nötig. Der Ordner des Beispiel-Themes sieht so aus:

lw-base/
├── style.css
├── theme.json
├── templates/
│   └── index.html
├── parts/
│   ├── header.html
│   └── footer.html
├── patterns/
│   └── footer-credits.php
└── styles/
    └── night.json

Die style.css trägt den Theme-Header. CSS muss sie bei einem Block-Theme nicht enthalten, denn die Gestaltung kommt aus der theme.json. Das Theme Handbook nennt für das Theme-Verzeichnis als Pflichtfelder Theme Name, Description, Version, Author, Text Domain, Tested up to, Requires at least, Requires PHP, License und License URI. Das Beispiel setzt Requires at least: 6.6, weil es theme.json in Version 3 verwendet, die mit WordPress 6.6 eingeführt wurde.

/*
Theme Name: LW Base
Theme URI: https://example.com/lw-base
Author: Lukas Wojcik
Author URI: https://lukaswojcik.com
Description: Minimal block theme with templates, template parts, a pattern and a style variation.
Version: 1.0.0
Requires at least: 6.6
Tested up to: 7.1
Requires PHP: 7.4
License: GNU General Public License v2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Text Domain: lw-base
*/

Die Ordnernamen stehen fest: Templates liegen in templates/, Template Parts in parts/, Patterns in patterns/ und Style Variations in styles/. Die alten Namen block-templates/ und block-template-parts/ erkennt WP_Theme::get_block_template_folders() weiterhin, allerdings nur als Rückfall für ältere Themes.

theme.json: settings, styles und Version 3

Die theme.json gliedert sich in zwei Hauptbereiche. settings legt fest, was der Editor anbietet: Farbpaletten, Schriftgrößen, Schriftfamilien, Layoutbreiten und freigeschaltete Gestaltungswerkzeuge. styles weist der ganzen Seite, Elementen wie Links und Überschriften sowie einzelnen Blocks konkrete Werte zu. Auf oberster Ebene kommen customTemplates, templateParts und patterns hinzu; das JSON-Schema für 7.1 führt außerdem title, slug, description und blockTypes, die für Style Variations gebraucht werden.

{
	"$schema": "https://schemas.wp.org/wp/7.1/theme.json",
	"version": 3,
	"settings": {
		"appearanceTools": true,
		"layout": {
			"contentSize": "720px",
			"wideSize": "1200px"
		},
		"color": {
			"defaultPalette": false,
			"palette": [
				{ "slug": "base", "color": "#ffffff", "name": "Base" },
				{ "slug": "contrast", "color": "#111827", "name": "Contrast" },
				{ "slug": "accent", "color": "#0369a1", "name": "Accent" }
			]
		},
		"typography": {
			"defaultFontSizes": false,
			"fontSizes": [
				{ "slug": "small", "size": "0.875rem", "name": "Small" },
				{ "slug": "medium", "size": "1rem", "name": "Medium" },
				{ "slug": "large", "size": "1.5rem", "name": "Large" }
			],
			"fontFamilies": [
				{
					"slug": "system",
					"name": "System",
					"fontFamily": "-apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, sans-serif"
				}
			]
		}
	},
	"styles": {
		"color": {
			"background": "var(--wp--preset--color--base)",
			"text": "var(--wp--preset--color--contrast)"
		},
		"typography": {
			"fontFamily": "var(--wp--preset--font-family--system)",
			"fontSize": "var(--wp--preset--font-size--medium)",
			"lineHeight": "1.6"
		},
		"spacing": {
			"padding": { "top": "1.5rem", "right": "1.5rem", "bottom": "1.5rem", "left": "1.5rem" }
		},
		"elements": {
			"link": {
				"color": { "text": "var(--wp--preset--color--accent)" }
			}
		}
	},
	"templateParts": [
		{ "name": "header", "title": "Header", "area": "header" },
		{ "name": "footer", "title": "Footer", "area": "footer" }
	]
}

Auf die Versionsnummer kommt es an. Die theme.json-Referenz auf developer.wordpress.org beschreibt Version 3, laut Block Editor Handbook eingeführt mit WordPress 6.6. Im Quelltext von 7.1 steht WP_Theme_JSON::LATEST_SCHEMA ebenfalls auf 3. Die Dev Note auf make.wordpress.org beschreibt die einzige inkompatible Änderung: Ab Version 3 kann ein Theme die Standard-Schriftgrößen und -Abstände nicht mehr stillschweigend ersetzen, indem es deren Slugs wiederverwendet. Wer Slugs wie small, medium und large mit eigenen Werten belegen will, muss defaultFontSizes (bzw. defaultSpacingSizes) auf false setzen, so wie im Beispiel. Ältere Versionen bleiben laut Block Editor Handbook weiter lauffähig.

Für den Schlüssel $schema gibt es zwei Varianten: https://schemas.wp.org/trunk/theme.json folgt der Entwicklung, https://schemas.wp.org/wp/7.1/theme.json ist an eine Version gebunden. Die Exportfunktion im Core schreibt die versionierte Form, und die ist auch für die Autovervollständigung im Editor die sicherere Wahl, weil das Trunk-Schema bereits Eigenschaften beschreiben kann, die die installierte Version nicht kennt. Alle drei JSON-Dateien dieses Beitrags wurden gegen das Schema für 7.1 validiert.

Das Array templateParts gibt jeder Datei in parts/ einen Titel und einen Bereich (area). Der Core definiert die Bereiche header, footer und uncategorized; seit 7.0 enthält der Quelltext zusätzlich navigation-overlay. Der Bereich bestimmt, wo der Site Editor den Part einordnet und welches HTML-Element ihn umschließt, falls kein tagName gesetzt ist.

Templates, Template Parts und ein Pattern

Ein Template ist eine HTML-Datei mit serialisierten Blocks. Die folgende index.html bindet Header und Footer ein, umschließt den Inhalt mit einem main-Element und verwendet den Query-Loop-Block mit "inherit":true. Damit zeigt er, was die Hauptabfrage der jeweiligen Anfrage liefert, also Blog-Übersicht, Archiv oder Suchergebnisse.

<!-- wp:template-part {"slug":"header","tagName":"header"} /-->

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
	<!-- wp:query {"queryId":1,"query":{"perPage":10,"pages":0,"offset":0,"postType":"post","order":"desc","orderBy":"date","inherit":true}} -->
	<div class="wp-block-query">
		<!-- wp:post-template -->
			<!-- wp:post-title {"isLink":true} /-->
			<!-- wp:post-excerpt /-->
		<!-- /wp:post-template -->

		<!-- wp:query-pagination -->
			<!-- wp:query-pagination-previous /-->
			<!-- wp:query-pagination-numbers /-->
			<!-- wp:query-pagination-next /-->
		<!-- /wp:query-pagination -->
	</div>
	<!-- /wp:query -->
</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

Template Parts werden über ihren Slug eingebunden. Das Attribut theme fehlt mit Absicht. Die Render-Funktion des Template-Part-Blocks greift ohne dieses Attribut auf get_stylesheet() zurück, also auf das aktive Theme. Stünde dort fest der Slug des Eltern-Themes, passte die Abfrage bei aktivem Child-Theme nicht mehr, und der Part würde als leerer String ausgegeben. Erst das fehlende Attribut erlaubt es einem Child-Theme, den Part zu ersetzen.

<!-- wp:group {"layout":{"type":"flex","justifyContent":"space-between"}} -->
<div class="wp-block-group">
	<!-- wp:site-title /-->
	<!-- wp:navigation /-->
</div>
<!-- /wp:group -->

<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group">
	<!-- wp:pattern {"slug":"lw-base/footer-credits"} /-->
</div>
<!-- /wp:group -->

Der Footer enthält keinen eigenen Text, sondern lädt ein Pattern. Pattern-Dateien in patterns/ registriert WordPress auf init automatisch, sofern der Dateikopf mindestens Title und Slug enthält; Dateien ohne diese Felder weist der Core mit einem _doing_it_wrong()-Hinweis ab. Da die Datei PHP ist, lassen sich Texte mit der Text Domain des Themes übersetzen, was in einem reinen HTML-Template nicht geht.

<?php
/**
 * Title: Footer credits
 * Slug: lw-base/footer-credits
 * Categories: footer
 * Block Types: core/template-part/footer
 * Description: Short credit line for the site footer.
 *
 * @package lw-base
 */

?>
<!-- wp:paragraph {"fontSize":"small"} -->
<p class="has-small-font-size"><?php esc_html_e( 'Published with a block theme.', 'lw-base' ); ?></p>
<!-- /wp:paragraph -->

Eine Style Variation ist eine unvollständige theme.json im Ordner styles/ und enthält nur, was von der Hauptdatei abweicht. Wählt jemand sie im Site Editor aus, landen ihre Daten laut Theme Handbook als Nutzeranpassung in der Datenbank. Spätere Änderungen an der Variation erreichen Websites, die sie bereits gespeichert haben, deshalb nicht mehr.

{
	"$schema": "https://schemas.wp.org/wp/7.1/theme.json",
	"version": 3,
	"title": "Night",
	"settings": {
		"color": {
			"palette": [
				{ "slug": "base", "color": "#0a0e14", "name": "Base" },
				{ "slug": "contrast", "color": "#e5e7eb", "name": "Contrast" },
				{ "slug": "accent", "color": "#38bdf8", "name": "Accent" }
			]
		}
	}
}

Was der Site Editor in die Datenbank schreibt

Solange niemand etwas anpasst, liest WordPress die Theme-Dateien direkt. Wird ein Template im Site Editor gespeichert, legt der Core das vollständige Block-Markup als Beitrag ab. Beteiligt sind drei Post Types: wp_template für Templates, wp_template_part für Template Parts und wp_global_styles für Änderungen an den globalen Stilen, einschließlich einer gewählten Style Variation. Der post_name eines Template-Beitrags ist der Template-Slug, etwa index oder single.

Die Taxonomie wp_theme ordnet diese Beiträge einem Theme zu. Ihr Term ist das Stylesheet, also der Ordnername des aktiven Themes. Ist ein Child-Theme aktiv, zählt dessen Ordnername statt des Ordnernamens des Eltern-Themes. get_block_templates() fragt nur Beiträge ab, deren Term get_stylesheet() entspricht. Template Parts tragen zusätzlich einen Term der Taxonomie wp_template_part_area. Intern hat jedes Template die ID stylesheet//slug, zum Beispiel lw-child//index.

Daraus folgt: Ein gespeichertes Template schlägt die Datei mit demselben Slug. get_block_templates() holt zuerst die Datenbanktreffer und übergibt deren Slugs anschließend als slug__not_in an die Dateisuche; die Theme-Datei wird also gar nicht mehr betrachtet. Ändert ein Theme-Update später templates/index.html, bleibt das unsichtbar, bis die Anpassung entfernt ist. Der REST-Controller für Templates erlaubt das Löschen nur bei Templates mit der Quelle custom; bei einem Template, das auf einer Theme-Datei beruht, stellt das Löschen des Beitrags die Dateifassung wieder her. Welche Anpassungen auf einer Website existieren, zeigt WP-CLI:

# Which templates, template parts and global styles live in the database?
wp post list --post_type=wp_template,wp_template_part,wp_global_styles --post_status=any --fields=ID,post_type,post_name,post_modified

# Which theme (stylesheet) does a customization belong to? 123 = an ID from the list above.
wp post term list 123 wp_theme --fields=name

Weil die Abfrage nach dem Stylesheet-Term filtert, macht ein Theme-Wechsel diese Beiträge unwirksam, entfernt sie aber nicht: Die Beiträge bleiben unter dem alten Term in der Datenbank und greifen wieder, sobald das Theme erneut aktiv ist. Der Export im Site Editor, umgesetzt in wp_generate_block_templates_export_file(), erzeugt ein ZIP mit den Theme-Dateien, den aktuellen Templates und Parts sowie einer theme.json, in der Theme-Daten und Nutzerdaten zusammengeführt sind.

Auflösung eines Templates: Datenbank, Child, Parent, Rückfall

Die Vorlagenhierarchie ist bei Block-Themes dieselbe wie bei klassischen Themes; das Theme Handbook vermerkt nur, dass HTML-Dateien an die Stelle der PHP-Dateien treten. Für einen einzelnen Beitrag erzeugt WordPress eine Liste von Kandidaten wie single-post-hallo-welt, single-post, single, singular und index. locate_block_template() reicht diese Liste an resolve_block_template() weiter, das get_block_templates() mit allen Kandidaten aufruft und die Treffer danach nach ihrer Position in der Hierarchie sortiert.

Je Slug gilt eine feste Reihenfolge der Quellen. Zuerst zählt ein wp_template-Beitrag für das aktive Stylesheet. Danach liest _get_block_templates_files() den Ordner templates/ des Child-Themes vor dem des Eltern-Themes; ein im Child gefundener Slug wird im Parent übersprungen. Es folgen Templates, die Plugins seit WordPress 6.7 mit register_block_template() registrieren, allerdings nur, wenn keine Theme-Datei mit demselben Slug existiert. Eigene HTML-Templates für Themes bringt WordPress nicht mit; der eigentliche Core-Rückfall ist deshalb der nächste, weniger spezifische Slug der Hierarchie bis hinunter zu index.html.

Der spezifischste Slug gewinnt immer, unabhängig von seiner Quelle. Eine single.html im Eltern-Theme schlägt also eine im Site Editor angepasste index.html, weil single in der Hierarchie vor index steht. Die Reihenfolge der Quellen entscheidet nur zwischen Einträgen mit gleichem Slug. Template Parts folgen demselben Muster: Die Render-Funktion des Template-Part-Blocks sucht erst einen wp_template_part-Beitrag und ruft dann get_block_file_template() auf, das über _get_block_template_file() zuerst das Stylesheet- und dann das Template-Verzeichnis durchsucht.

Ausgegeben wird das gefundene Block-Markup über wp-includes/template-canvas.php. Ist ein gespeichertes Template leer, sehen angemeldete Nutzer seit 6.8 einen Hinweis mit Link zum Site Editor; Besucher bekommen stattdessen den Inhalt der Theme-Datei, sofern es eine gibt.

Ein Child-Theme für ein Block-Theme

Zwingend braucht ein Child-Theme nur die style.css mit dem Header Template. Laut Theme Handbook muss dessen Wert exakt dem Ordnernamen des Eltern-Themes entsprechen. Das Beispiel-Child bringt zusätzlich eine eigene Palette und einen geänderten Header mit.

lw-child/
├── style.css
├── theme.json
└── parts/
    └── header.html

/*
Theme Name: LW Child
Template: lw-base
Description: Child theme of LW Base with its own palette and header.
Version: 1.0.0
Requires at least: 6.6
Tested up to: 7.1
Requires PHP: 7.4
License: GNU General Public License v2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Text Domain: lw-child
*/

Eine eigene templates/index.html ist im Child nicht nötig. WP_Theme::get_file_path() sucht zuerst im Stylesheet- und danach im Template-Verzeichnis, daher findet is_block_theme() die Datei des Eltern-Themes und behandelt auch das Child als Block-Theme. Was im Child fehlt, kommt aus dem Parent: Templates, Template Parts, Patterns und Style Variations.

Überschrieben wird Stück für Stück. Eine gleichnamige Datei in templates/ oder parts/ ersetzt die Fassung des Eltern-Themes. Bei Patterns zählt in _register_theme_block_patterns() nicht der Dateiname, sondern der Slug im Dateikopf: Die Patterns des Childs werden zuerst registriert, ein Parent-Pattern mit bereits vergebenem Slug wird übersprungen. Bei Style Variations vergleicht get_style_variations() die Dateinamen beider styles/-Ordner und behält bei Gleichheit nur die Datei des Childs. Der ersetzte Header im Child sieht so aus:

<!-- wp:group {"layout":{"type":"flex","justifyContent":"space-between"}} -->
<div class="wp-block-group">
	<!-- wp:group {"layout":{"type":"flex","orientation":"vertical"}} -->
	<div class="wp-block-group">
		<!-- wp:site-title /-->
		<!-- wp:site-tagline /-->
	</div>
	<!-- /wp:group -->
	<!-- wp:navigation /-->
</div>
<!-- /wp:group -->

Aus dem Stylesheet-Term folgt noch eine praktische Einzelheit. Anpassungen, die im Site Editor bei aktivem Eltern-Theme entstanden sind, gehören zu dessen Stylesheet. Nach dem Wechsel auf das Child greifen sie nicht mehr; das Child startet mit den Dateien.

Wie die theme.json von Parent und Child zusammengeführt wird

Globale Einstellungen und Stile stammen aus vier Quellen, die WP_Theme_JSON_Resolver::get_merged_data() in fester Reihenfolge zusammenführt: default (die theme.json des Cores), blocks (Daten aus Block-Registrierungen), theme und custom (Nutzerdaten aus dem wp_global_styles-Beitrag). Jede spätere Ebene überschreibt die früheren. Die Code-Dokumentation nennt als Beispiel eine Hintergrundfarbe für den Absatz-Block, die sowohl Theme als auch Nutzer setzen: Die Nutzereinstellung gewinnt.

Die Ebene theme setzt sich selbst aus mehreren Teilen zusammen. get_theme_data() liest zuerst die theme.json des aktiven Themes, also des Childs. Gibt es ein Eltern-Theme mit einer anderen theme.json, erzeugt der Resolver aus der Parent-Datei ein WP_Theme_JSON-Objekt und führt die Child-Daten hinein; laut Kommentar im Quelltext hat das Child Vorrang. Zum Schluss wird dieses Ergebnis über die Werte aus add_theme_support() gelegt, sodass die theme.json Theme Supports schlägt.

{
	"$schema": "https://schemas.wp.org/wp/7.1/theme.json",
	"version": 3,
	"settings": {
		"color": {
			"palette": [
				{ "slug": "base", "color": "#f4f6f9", "name": "Base" },
				{ "slug": "contrast", "color": "#111827", "name": "Contrast" },
				{ "slug": "accent", "color": "#c2410c", "name": "Accent" }
			]
		}
	},
	"styles": {
		"elements": {
			"heading": {
				"typography": { "fontWeight": "700" }
			}
		}
	}
}

Das Zusammenführen selbst, WP_Theme_JSON::merge(), arbeitet mit array_replace_recursive(); verschachtelte Objekte werden also Schlüssel für Schlüssel kombiniert. Im Beispiel bleiben Layout, Typografie und Linkfarbe des Parents erhalten, das Child ergänzt das Schriftgewicht der Überschriften.

Presets sind die Ausnahme: Paletten, Verläufe, Duotone-Filter, Schriftgrößen, Schriftfamilien und die übrigen Preset-Listen, etwa Abstandsgrößen und Schatten, werden jeweils als ganze Liste ersetzt. Die Palette des Childs ersetzt deshalb die Palette des Parents, statt sie zu erweitern.

Deshalb wiederholt das Child alle drei Slugs. Stünde dort nur accent, fehlten base und contrast, und jeder Stil, der auf sie verweist, verlöre seinen Wert. Die wirksame Theme-Palette lässt sich auf einer Testinstallation prüfen:

wp eval 'echo wp_json_encode( wp_get_global_settings( array( "color", "palette", "theme" ), array( "origin" => "base" ) ), JSON_PRETTY_PRINT );'

Die Option "origin" => "base" lässt die Nutzerebene weg, die Ausgabe zeigt also nur das zusammengeführte Ergebnis aus Parent und Child.

Grenzen und offene Punkte

• Der Filter wp_theme_json_data_theme erhält die Daten des Childs, bevor die Parent-Datei eingemischt wird. Ein Callback, der die vollständigen Theme-Daten erwartet, sieht bei aktivem Child-Theme nur den Child-Anteil.
• Mischformen mit PHP-Templates folgen zusätzlichen Regeln. Findet locate_template() eine PHP-Datei, kommen nur Block-Templates mit gleicher oder höherer Spezifität in Frage, und ein PHP-Template im Child kann Vorrang vor einem gleichnamigen Block-Template im Parent haben.
• Das Theme Handbook beschreibt, dass Patterns im Child durch eine gleichnamige Datei überschrieben werden; der Quelltext von 7.1 vergleicht Slugs. Dieser Beitrag folgt dem Quelltext.
• Einige Handbook-Seiten zeigen in ihren Beispielen noch "version": 2, während die Referenz Version 3 beschreibt.
• Die Beispiele wurden am 30.09.2026 unter WordPress 7.1.2 getestet: Beide Themes lassen sich ohne Meldungen aktivieren, das Child gilt ohne eigene index.html als Block-Theme, das Block-Markup besteht die Prüfung im Site Editor, und der Vorrang der Templates, die Folgen eines Theme-Wechsels und das Ersetzen der Palette verhalten sich wie beschrieben. Ein verwandtes Thema behandelt der Beitrag zur Sicherheitslücke bei Seitenvorlagen in WordPress 7.1.2.