Warum wird mein Block-Template in WordPress nicht angewendet?

Meist, weil eine in der Datenbank gespeicherte Fassung die Datei überstimmt. Sobald Sie ein Template im Site-Editor bearbeiten und speichern, legt WordPress einen wp_template-Beitrag an und liefert diesen statt der .html-Datei aus Ihrem Theme-Ordner aus. Jede spätere Änderung an der Datei bleibt im Frontend unsichtbar.

Wohin gehören Block-Template-Dateien in einem WordPress-Theme?

Vollständige Templates kommen in einen Ordner templates im Wurzelverzeichnis des Themes, wiederverwendbare Abschnitte in einen Ordner parts. Beide verwenden die Endung .html, kleingeschriebene Dateinamen und Bindestriche statt Unterstriche. Außerdem muss templates/index.html vorhanden sein, sonst behandelt WordPress das Theme gar nicht erst als Block-Theme.

Was ist der Unterschied zwischen einem Template und einem Template-Teil?

Ein Template rendert eine ganze Seite und wird über die Template-Hierarchie anhand der aufgerufenen Ansicht ausgewählt. Ein Template-Teil ist ein Fragment wie Kopf- oder Fußbereich, das ein Template einbindet. Wer einen Header-Teil bearbeitet, verändert jedes Template, das ihn einbindet – deshalb wirken Änderungen an Teilen oft so, als hätten sie an der falschen Stelle gegriffen.

Kann Caching dafür sorgen, dass Block-Templates nicht aktualisiert werden?

Manchmal, aber es ist die unwahrscheinlichste Ursache und gehört ans Ende der Prüfliste. Seiten-Caches und persistente Objekt-Caches können veraltetes Markup festhalten, leeren Sie also beide, bevor Sie Schlüsse ziehen. OPcache zu leeren bringt hier gar nichts, denn Block-Templates sind .html-Dateien und werden von PHP überhaupt nie kompiliert.

Warum funktioniert mein Template mit Seiten-Slug plötzlich nicht mehr?

Slug-basierte Templates werden zur Laufzeit gegen den aktuellen Beitrags-Slug abgeglichen. Wird eine Seite umbenannt, ändert sich ihr Slug, und page-about.html greift stillschweigend nicht mehr, sobald die Seite about-us heißt. Dasselbe gilt für Kategorie- und Schlagwort-Templates. Benennen Sie entweder die Datei passend zum neuen Slug um oder weisen Sie das Template in der Seitenleiste des Beitragseditors ausdrücklich zu.

Block-Template wird nicht angewendet? Fangen Sie bei der Datenbank an

Q: Wie bringe ich WordPress dazu, meine Theme-Datei statt der Site-Editor-Fassung zu verwenden?

Öffnen Sie Design, dann Editor, dann Templates, suchen Sie das Template und wählen Sie in dessen Optionsmenü das Löschen der Anpassungen beziehungsweise Zurücksetzen. Damit wird der Datenbankeintrag entfernt und die Kontrolle geht zurück an die Datei auf der Festplatte. Bietet das Menü statt Zurücksetzen nur Löschen an, existiert das Template ausschließlich in der Datenbank und hat keine Datei dahinter.

Ihre Template-Datei wird mit ziemlicher Sicherheit deshalb ignoriert, weil eine Fassung in der Datenbank gewinnt. In dem Moment, in dem Sie ein Template im Site-Editor öffnen und auf Speichern drücken, schreibt WordPress einen wp_template-Beitrag – und von da an wird dieser Datensatz statt der .html-Datei aus Ihrem Theme-Ordner ausgeliefert. Jede spätere Änderung an der Datei bleibt im Frontend unsichtbar. Diesen Datensatz zu löschen ist die Lösung, und es ist das Erste, was Sie prüfen sollten, bevor Sie sich mit Hierarchie, Dateinamen oder Cache befassen.

Bestätigen, dass die Datenbankfassung existiert

Gehen Sie zu Design → Editor → Templates. Jedes Template, das WordPress aus der Datenbank ausliefert, ist in der Liste markiert – je nach WordPress-Version lautet die Kennzeichnung „Angepasst” oder das Template erscheint unter einem entsprechenden Filter. Diese Kennzeichnung ist bereits die ganze Antwort. Ist sie da, wird Ihre Datei nicht verwendet.

Dasselbe lässt sich über die Kommandozeile prüfen, was schneller geht und selbst dann funktioniert, wenn der Site-Editor sich merkwürdig verhält:

wp post list --post_type=wp_template --fields=ID,post_name,post_status,post_title
wp post list --post_type=wp_template_part --fields=ID,post_name,post_status,post_title

Jede Zeile ist eine Überschreibung aus der Datenbank. post_name entspricht dem Template-Slug, eine Zeile mit dem Namen single verdeckt also templates/single.html.

Ein Detail, über das viele stolpern: Diese Datensätze sind über einen Taxonomie-Begriff an ein Theme gebunden, nicht über einen Pfad. Benennen Sie den Ordner Ihres Themes um, bleiben die gespeicherten Templates zwar in der Datenbank, passen aber nicht mehr zum aktiven Theme – und die Website fällt schlagartig auf die Dateien zurück. Das sieht dann nach „meine Anpassungen sind verschwunden” aus statt nach „meine Datei wird ignoriert” – gleicher Mechanismus, umgekehrtes Symptom.

Löschen

Öffnen Sie im Site-Editor das Optionsmenü des Templates (die drei Punkte daneben) und wählen Sie Anpassungen löschen – manche Versionen beschriften den Eintrag als Zurücksetzen. Damit wird der Datenbankeintrag entfernt und die Kontrolle geht zurück an die Datei auf der Festplatte.

Bietet das Menü statt Anpassungen löschen oder Zurücksetzen nur Löschen an, existiert dieses Template ausschließlich in der Datenbank und hat keine Datei dahinter. Löschen entfernt das Template vollständig, und WordPress fällt die Hierarchie weiter hinunter.

Über WP-CLI, mit einer ID aus der obigen Liste:

wp post delete 482 --force

Seien Sie sich über den Preis im Klaren: Beim Löschen der Anpassungen geht alles unwiederbringlich verloren, was Sie für dieses Template im Site-Editor aufgebaut haben. Steckt in der Site-Editor-Fassung echte Arbeit, kopieren Sie das Block-Markup vorher heraus – Template im Editor öffnen, in die Code-Ansicht wechseln und das Ergebnis in Ihre .html-Datei einfügen. So wird die Datei zur maßgeblichen Quelle und nichts geht verloren.

Wie WordPress ein Template auswählt

Block-Themes verwenden dieselbe Hierarchielogik wie Classic-Themes, nur mit .html-Dateien in templates/ statt .php-Dateien im Theme-Wurzelverzeichnis. WordPress arbeitet sich vom Speziellsten zum Allgemeinsten vor und nimmt die erste Datei, die existiert.

Aufgerufene Ansicht	Prüfreihenfolge
Ein einzelner Beitrag	`single-post-{slug}.html` → `single-post.html` → `single.html` → `singular.html` → `index.html`
Eine Seite	`page-{slug}.html` → `page-{id}.html` → `page.html` → `singular.html` → `index.html`
Ein Kategorie-Archiv	`category-{slug}.html` → `category-{id}.html` → `category.html` → `archive.html` → `index.html`
Ein eigener Inhaltstyp	`single-{post-type}.html` → `single.html` → `singular.html` → `index.html`
Die 404-Seite	`404.html` → `index.html`

Zwei Dinge setzen das komplett außer Kraft. Erstens der oben beschriebene Datenbankeintrag. Zweitens ein Template, das direkt einem Beitrag oder einer Seite zugewiesen wurde – öffnen Sie den Beitragseditor, suchen Sie das Template-Panel in der Seitenleiste und prüfen Sie, ob dort etwas Bestimmtes ausgewählt ist. Eine ausdrückliche Zuweisung schlägt die Hierarchie jedes Mal, und sie ist unsichtbar, solange Sie nicht gezielt nachsehen.

Slug-basierte Templates sind auf eine Weise fragil, die man verinnerlicht haben sollte. page-about.html greift nur, solange der Slug der Seite about lautet. Benennen Sie die Seite in about-us um, hört das Template ohne Warnung und ohne Fehlermeldung auf zu greifen.

Template gegen Template-Teil

Ein Template rendert eine komplette Ansicht und wird über die Hierarchie ausgewählt. Ein Template-Teil ist ein Fragment – Kopfbereich, Fußbereich, Seitenleiste –, das Templates einbinden. Teile liegen in parts/, Templates in templates/, und in der Datenbank werden sie getrennt als wp_template_part-Datensätze abgelegt.

Die typische Verwirrung: Sie bearbeiten den Kopfbereich, und die Änderung taucht auf Seiten auf, die Sie gar nicht anfassen wollten. Das ist korrektes Verhalten. Ein Teil wird von jedem Template geteilt, das ihn einbindet. Wollen Sie in einem Template einen anderen Kopfbereich, brauchen Sie eine zweite Teil-Datei und ein Template, das darauf verweist – den gemeinsamen Teil zu bearbeiten führt niemals zu Unterschieden je Template.

Der umgekehrte Fall kommt ebenfalls vor: Sie legen ein vollständiges Seitenlayout in parts/ ab und wundern sich, warum die Hierarchie es nie aufgreift. Teile sind in der Hierarchie überhaupt keine Kandidaten; nichts wird jemals direkt auf sie geleitet.

Dateinamen und Ablageort

Prüfen Sie das hier, bevor Sie Exotischeres vermuten:

Der Ordner heißt templates/, im Plural, im Wurzelverzeichnis des Themes. Nicht template/, nicht block-templates/. block-templates/ war zur Zeit des Gutenberg-Plugins der richtige Name, bevor Block-Themes in den Core kamen, und etliche Tutorials zeigen ihn noch immer – im aktuellen WordPress funktioniert er nicht.
Template-Teile kommen in parts/, nicht in template-parts/ (das ist die Classic-Theme-Konvention für PHP-Teilstücke).
Die Endung lautet .html. Eine .php-Datei in templates/ wird ignoriert.
Dateinamen sind kleingeschrieben und verwenden Bindestriche. single-Post.html oder single_post.html greifen nicht. Auf einem Dateisystem ohne Groß-/Kleinschreibungsunterschied wie unter macOS funktioniert das lokal und bricht auf einem Linux-Server – das klassische „bei mir läuft es”.
templates/index.html muss vorhanden sein. Ohne diese Datei stuft WordPress das Theme nicht als Block-Theme ein, und der Site-Editor erscheint unter Umständen gar nicht.
Arbeiten Sie in einem Child-Theme, haben dessen Templates Vorrang vor denen des Eltern-Themes. Eine übrig gebliebene Datei im Child-Theme schlägt klammheimlich die Elterndatei, die Sie gerade bearbeiten.

Eigene Templates, die im Beitragseditor auswählbar sein sollen, müssen zusätzlich in theme.json unter customTemplates deklariert werden – mit dem Basisnamen der Datei, einem lesbaren Titel und den Inhaltstypen, für die sie gelten. Ohne diesen Eintrag existiert die Datei zwar, taucht im Template-Panel aber nie auf.

Caching – zuletzt prüfen

Caching ist ein reales Problem, aber die unwahrscheinlichste Ursache. Zuerst dort zu suchen ist der übliche Weg, einen Nachmittag zu verlieren.

Leeren Sie Ihren Seiten-Cache und, falls Sie einen persistenten Objekt-Cache wie Redis oder Memcached betreiben, auch diesen – Ergebnisse der Template-Auflösung können dort gehalten werden. Laden Sie anschließend unter Umgehung des Browser-Caches neu.

Was nicht hilft: OPcache zu leeren. Block-Templates sind .html-Dateien und werden von PHP nie kompiliert, OPcache hat mit ihnen also nichts zu tun. Wenn ein OPcache-Flush das Problem bei Ihnen einmal behoben zu haben schien, hat sich zeitgleich etwas anderes geändert.

Immer noch fest?

Wenn kein Datenbankeintrag existiert, der Dateiname stimmt, dem Beitrag kein Template ausdrücklich zugewiesen ist und die Caches bereits geleert sind, sehen Sie sich die Plugins an. Alles, was die Template-Auflösung filtert – ein Page-Builder, ein Mitglieder-Plugin, ein Mehrsprachigkeits-Plugin, ein LMS – kann spät im Request ein eigenes Template unterschieben. Wechseln Sie auf ein Standard-Block-Theme und testen Sie mit deaktivierten Plugins, dann aktivieren Sie eines nach dem anderen wieder.

Und falls das Template doch greift, aber leer rendert, ist das ein anderes Problem: Prüfen Sie, ob das Block-Markup in der Datei gültig ist. Ein fehlerhafter Block-Kommentar kann dazu führen, dass der Editor Inhalte stillschweigend entfernt, statt einen Fehler zu melden.