So erstellen Sie ein WordPress-Child-Theme

Um ein WordPress-Child-Theme zu erstellen, legen Sie in wp-content/themes einen neuen Ordner an. Darin platzieren Sie eine style.css, deren Template-Header dem Ordnernamen des Parent-Themes entspricht. Anschließend aktivieren Sie das Theme. Das Child-Theme erbt Templates, Styles und Funktionen des Parent-Themes und enthält nur Ihre Änderungen.

Vielleicht haben Sie schon einmal die Dateien eines Themes direkt bearbeitet und dann zugesehen, wie das nächste Update alles überschrieben hat. Genau das verhindert ein Child-Theme.

Dieser Leitfaden beschreibt das Setup, das in aktuellen WordPress-Versionen funktioniert. Er führt Sie durch ein klassisches Child-Theme mit korrekt eingebundenen Stylesheets sowie durch das Überschreiben von Templates und Funktionen. Außerdem erfahren Sie, was sich bei Block-Themes wie Twenty Twenty-Four ändert und in welchen Fällen Sie überhaupt kein Child-Theme benötigen.

Warum scheitert die direkte Bearbeitung eines Parent-Themes?

Bei einem Theme-Update ersetzt WordPress die Theme-Dateien durch die neue Version. Jede Änderung, die Sie im Theme-Ordner vorgenommen haben, geht dabei verloren. Ein Child-Theme speichert Ihre Änderungen in einem separaten Ordner, den Updates nie anrühren. Der Child-Theme-Leitfaden im Theme Handbook beschreibt dies als den Weg, Updates des Parent-Themes zu übernehmen, ohne auf eigene Anpassungen verzichten zu müssen. Das Theme-System kennt nur zwei Ebenen, Parent und Child. Ein „Grandchild-Theme“ darüber lässt sich also nicht installieren.

So erstellen Sie ein Child-Theme in WordPress (klassische Themes)

Ein klassisches Child-Theme benötigt einen Ordner und eine style.css mit Template-Header. In den meisten Fällen kommt eine functions.php hinzu, die das Stylesheet einbindet. Der Aufbau entspricht der Struktur aus Ordner, style.css und functions.php, die auch unser Leitfaden zum Erstellen eines responsiven WordPress-Themes mit Bootstrap beschreibt. Der Unterschied: Das Child-Theme enthält nur das, was es tatsächlich ändert.

wp-content/themes/
├── twentytwentyfour/
└── tt4-child/
    ├── style.css
    └── functions.php

Der style.css-Header

Zwingend erforderlich ist nur die style.css. Laut der Dokumentation zum Main Stylesheet benötigt jedes Theme mindestens einen Theme Name-Header. Ein Child-Theme ergänzt zusätzlich den Header Template.

/*
 * Theme Name:  TT4 Child
 * Template:    twentytwentyfour
 * Version:     1.0.0
 * Text Domain: tt4-child
 */

Template erwartet den Ordnernamen des Parent-Themes, nicht dessen Anzeigenamen. Stimmen die beiden nicht Zeichen für Zeichen überein, verknüpft WordPress das Child-Theme nicht mit seinem Parent-Theme.

Stylesheets einbinden statt @import

Binden Sie die Styles des Child-Themes mit wp_enqueue_style() über den Hook wp_enqueue_scripts ein, nicht mit @import. Viele ältere Tutorials laden die Parent-Styles per @import am Anfang der style.css des Child-Themes. Dieser Ansatz ist veraltet:

/* Outdated: do not use */
@import url("../twentytwentyfour/style.css");

Der Browser entdeckt die importierte Datei erst, nachdem er das Child-Stylesheet heruntergeladen und geparst hat. Die beiden Requests erfolgen daher nacheinander, und beide blockieren das Rendering. Zudem liegt der Import außerhalb des Enqueue-Systems von WordPress. WordPress kann daher weder seine Abhängigkeiten verwalten noch ihn versionieren oder Duplikate vermeiden.

Der Ersatz ist wp_enqueue_style(), aufgerufen in einer Funktion, die am Hook wp_enqueue_scripts hängt. Über denselben Hook werden auch Skripte geladen. Mehr dazu lesen Sie in unserem Artikel über das Hinzufügen von eigenem JavaScript zu WordPress-Themes.

<?php
// functions.php
add_action( 'wp_enqueue_scripts', 'tt4child_enqueue_styles' );

function tt4child_enqueue_styles() {
	wp_enqueue_style(
		'tt4child-style',
		get_stylesheet_uri(), // the active (child) theme's style.css
		array(),              // $deps: handles that must load first
		'1.0.0'               // $ver: appended as a cache-busting query string
	);
}

Welcher Enqueue-Code für ein Child-Theme der richtige ist, hängt davon ab, was das Parent-Theme bereits einbindet:

Für die dritte Zeile verwenden Sie folgenden Code:

function tt4child_enqueue_styles() {
	wp_enqueue_style(
		'tt4child-parent-style',
		get_parent_theme_file_uri( 'style.css' )
	);
}

Um herauszufinden, welcher Fall vorliegt, durchsuchen Sie die functions.php des Parent-Themes nach wp_enqueue_style oder suchen im Seitenquelltext nach <link>-Tags für Stylesheets. Die Reihenfolge der Stylesheets ist nicht festgelegt. Sie richtet sich nach den Enqueue-Aufrufen. Das Argument $deps nimmt ein Array registrierter Handles entgegen, die zuerst geladen werden müssen. Damit das Child-Stylesheet nach dem Parent-Stylesheet ausgegeben wird, übergeben Sie das Handle des Parent-Themes in $deps. Den Namen des Handles entnehmen Sie dem Code des Parent-Themes. Ist die URL eines Child-Stylesheets falsch, liefert der Request einen 404-Fehler, und die Seite wird nur mit dem CSS des Parent-Themes gerendert. Ein Session Replay, das Netzwerk-Requests parallel zur visuellen Wiedergabe aufzeichnet, zeigt den fehlgeschlagenen Request neben der ungestylten Seite.

Wie überschreiben Sie Templates des Parent-Themes?

Um ein Template des Parent-Themes zu überschreiben, kopieren Sie die Datei (verschieben Sie sie nicht) in denselben relativen Pfad im Child-Theme. Beim Abarbeiten der Template-Hierarchie prüft WordPress den Child-Ordner vor dem Parent-Ordner, sodass eine gleichnamige Datei im Child-Theme verwendet wird. Wenn Sie die Datei verschieben statt kopieren, verändern Sie das Parent-Theme, und das nächste Update stellt sie ohnehin wieder her.

twentytwentyfour/page.php  →  copy to  →  tt4-child/page.php

Dieselbe Regel gilt für Template Parts. Sie können außerdem neue Templates hinzufügen, die das Parent-Theme nicht enthält.

Funktionen des Parent-Themes überschreiben

Die functions.php eines Child-Themes ersetzt nicht die des Parent-Themes. Laut Handbook führt WordPress beide Dateien aus: zuerst die des Child-Themes, unmittelbar danach die des Parent-Themes. Aus dieser Ladereihenfolge ergeben sich zwei Konsequenzen. Parent-Funktionen, die in function_exists() gekapselt sind (sogenannte Pluggable Functions), lassen sich im Child-Theme neu definieren. Alle anderen Parent-Funktionen müssen ausgehängt oder ergänzt werden. Kopieren Sie auch nicht den Code der functions.php des Parent-Themes in das Child-Theme: Werden dieselben Funktionsnamen zweimal deklariert, bricht die Website mit einem Fatal Error ab.

Eine Pluggable Function im Parent-Theme sieht so aus:

// Parent theme
if ( ! function_exists( 'parenttheme_credit' ) ) {
	function parenttheme_credit() { /* ... */ }
}

Da das Child-Theme zuerst ausgeführt wird, sorgt eine gleichnamige Definition im Child-Theme dafür, dass die Version des Parent-Themes übersprungen wird:

// Child theme
function parenttheme_credit() {
	echo '<p>Custom credit line</p>';
}

Ist die Funktion nicht pluggable, entfernen Sie sie mit remove_action(). Verwenden Sie dabei denselben Hook und dieselbe Priorität, mit der sie registriert wurde. Ein remove_action()-Aufruf auf oberster Ebene der Child-Datei läuft, bevor das Parent-Theme seinen Hook hinzugefügt hat. Es gibt also noch nichts zu entfernen. Führen Sie den Aufruf daher über after_setup_theme aus. Dieser Hook wird ausgelöst, sobald die functions.php-Dateien beider Themes geladen sind:

// Parent theme
add_action( 'init', 'parenttheme_setup_extra', 20 );

// Child theme
add_action( 'after_setup_theme', function () {
	remove_action( 'init', 'parenttheme_setup_extra', 20 );
} );

remove_filter() funktioniert für Filter auf die gleiche Weise. Wenn Sie eine Parent-Funktion ergänzen statt ersetzen möchten, hängen Sie Ihre eigene Funktion mit einer späteren Priorität an denselben Hook. Die Standardpriorität von add_action() ist 10, höhere Werte werden später ausgeführt:

add_action( 'parent_footer', 'tt4child_footer_extra', 20 );

Wie funktionieren Child-Themes bei Block-Themes?

Ein Child-Theme für ein Block-Theme, etwa auf Basis von Twenty Twenty-Four, benötigt oft nur style.css und theme.json. Das Styling liegt größtenteils in der theme.json. Das Handbook weist daher darauf hin, dass das Einbinden der style.css häufig unnötig ist. Viele Block-Child-Themes kommen ganz ohne functions.php aus.

tt4-child/
├── style.css
├── theme.json
├── templates/
│   └── single.html
├── parts/
│   └── header.html
└── patterns/
    └── (same filename as the parent pattern).php

Um ein Template, ein Template Part oder ein Pattern zu überschreiben, fügen Sie eine gleichnamige Datei hinzu. Bei Patterns muss zusätzlich der registrierte Slug-Header mit dem des Parent-Themes übereinstimmen. Kopieren Sie ihn daher aus der Parent-Datei:

<?php
/**
 * Title: Footer
 * Slug: parent-slug/pattern-name
 */
?>

Eine minimale theme.json legt das Schema fest und verwendet Version 3, die WordPress 6.6 oder neuer voraussetzt:

{
	"$schema": "https://schemas.wp.org/wp/6.6/theme.json",
	"version": 3,
	"styles": {
		"typography": {
			"lineHeight": "1.7"
		}
	}
}

Die theme.json-Dateien von Parent- und Child-Theme werden nach festgelegten Merge-Regeln zusammengeführt, wobei die Werte des Child-Themes Vorrang haben. Im Website-Editor (Site Editor) gespeicherte Anpassungen werden zusätzlich in der Datenbank abgelegt und stehen im Ebenenmodell des Handbooks über dem Child-Theme. Scheint ein Child-Template ignoriert zu werden, setzen Sie die gespeicherte Anpassung dieses Templates im Website-Editor zurück.

Wann Sie kein Child-Theme benötigen

Für kleine optische Anpassungen oder funktionale Erweiterungen brauchen Sie kein Child-Theme. Bei einem klassischen Theme genügt für einige wenige Regeln das Feld „Zusätzliches CSS“ im Customizer. Ist ein Block-Theme aktiv, hinterlegen Sie eigenes CSS stattdessen im Bereich „Stile“ des Website-Editors. Funktionale Änderungen wie Custom Post Types gehören in ein Plugin, damit sie auch nach einem Theme-Wechsel funktionieren. Werden Ihre Änderungen so umfangreich, dass sich das Child-Theme nur noch schwer verwalten lässt, empfiehlt das Handbook, das Parent-Theme zu forken und daraus ein eigenes Theme zu machen.

Fazit

Im Kern besteht ein Child-Theme aus einem Ordner und einer style.css, deren Template-Wert dem Ordnernamen des Parent-Themes entspricht. Bei klassischen Themes ergänzen Sie Enqueue-Code, der zu dem passt, was das Parent-Theme lädt. Bei Block-Themes übernehmen theme.json und gleichnamige Template-Dateien diese Aufgabe. Prüfen Sie zunächst, welche Stylesheets Ihr Parent-Theme einbindet, und fügen Sie dann nur die Dateien hinzu, die Sie tatsächlich ändern müssen.

FAQs

Was ist der Unterschied zwischen get_template_directory_uri() und get_stylesheet_directory_uri() in einem Child-Theme?

Ist ein Child-Theme aktiv, liefert get_template_directory_uri() die Verzeichnis-URL des Parent-Themes, während get_stylesheet_directory_uri() die Verzeichnis-URL des Child-Themes zurückgibt. Verwenden Sie die Stylesheet-Variante für Dateien, die im Child-Theme liegen. Seit WordPress 4.7 ist get_theme_file_uri() oft die bessere Wahl: Die Funktion gibt die Kopie einer Datei im Child-Theme zurück, sofern vorhanden, und greift andernfalls auf die Datei des Parent-Themes zurück.

Warum sind meine Customizer-Einstellungen und Menüpositionen nach dem Aktivieren eines Child-Themes verschwunden?

WordPress speichert Customizer-Einstellungen (Theme Mods) für jedes Theme separat, verknüpft mit dem Ordnernamen des aktiven Themes. Ein Child-Theme startet daher mit eigenen, leeren Einstellungen und übernimmt die des Parent-Themes nicht. Ihre Menüs sind weiterhin vorhanden, Sie müssen sie jedoch erneut den Menüpositionen zuweisen und die übrigen Einstellungen neu eingeben oder importieren. Die Einstellungen des Parent-Themes bleiben in der Datenbank erhalten und stehen wieder zur Verfügung, wenn Sie zum Parent-Theme zurückwechseln.

Was passiert mit einer in ein Child-Theme kopierten Template-Datei, wenn das Parent-Theme aktualisiert wird?

Die Kopie im Child-Theme bleibt genau so, wie Sie sie gespeichert haben, und WordPress verwendet sie weiterhin anstelle der aktualisierten Datei des Parent-Themes. Bugfixes, Sicherheitspatches oder Markup-Änderungen, die das Parent-Theme an dieser Datei vornimmt, erreichen Ihre Überschreibung nie. Vergleichen Sie nach jedem Update des Parent-Themes Ihre überschriebenen Dateien mit den neuen Parent-Versionen und übernehmen Sie, was Sie benötigen. Überschreiben Sie so wenige Dateien wie möglich, damit dieser Aufwand überschaubar bleibt.

Kann ich ein Child-Theme für ein Block-Theme erstellen, ohne Code zu schreiben?

Ja. Das offizielle Plugin Create Block Theme auf WordPress.org bietet die Option „Create Child Theme“. Es erzeugt ein Child-Theme des aktiven Block-Themes, etwa von Twenty Twenty-Four, und schreibt die im Website-Editor vorgenommenen Änderungen in die Dateien des Child-Themes. Das Plugin ist für Block-Themes konzipiert. Ein Child-Theme eines klassischen Parent-Themes erfordert daher weiterhin das oben beschriebene Setup mit style.css und functions.php.