Block template werkt niet in WordPress? Begin bij de database

Je sjabloonbestand wordt vrijwel zeker genegeerd omdat een kopie in de database wint. Zodra je een sjabloon in de site-editor opent en op Opslaan drukt, schrijft WordPress een wp_template-bericht weg, en vanaf dat moment wordt dat record geserveerd in plaats van het .html-bestand in je themamap — dus elke wijziging die je daarna in het bestand maakt, is aan de voorkant onzichtbaar. Dat record wissen is de oplossing, en het is het eerste dat je controleert, nog voor de hiërarchie, de bestandsnaam of de cache.

Bevestig dat de databasekopie bestaat

Ga naar Weergave → Editor → Sjablonen. Elk sjabloon dat WordPress vanuit de database serveert, is in de lijst gemarkeerd — afhankelijk van je WordPress-versie staat er een label “Aangepast” of verschijnt het sjabloon onder een filter “Aangepast”. Dat label is het hele antwoord. Staat het er, dan wordt jouw bestand niet gebruikt.

Je kunt hetzelfde vanaf de commandoregel controleren, wat sneller gaat en zelfs werkt als de site-editor zich vreemd gedraagt:

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

Elke regel is een databaseoverschrijving. De post_name komt overeen met de sjabloonslug, dus een regel met de naam single overschaduwt templates/single.html.

Eén detail waar mensen over struikelen: deze records zijn via een taxonomieterm aan een thema gekoppeld, niet via een pad. Hernoem je de map van je thema, dan blijven de opgeslagen sjablonen in de database staan maar matchen ze niet meer met het actieve thema, waarna de site plotseling terugvalt op de bestanden. Dat voelt als “mijn aanpassingen zijn weg” in plaats van “mijn bestand wordt genegeerd” — hetzelfde mechanisme, tegenovergesteld symptoom.

Wis het

Open in de site-editor het optiesmenu van het sjabloon (de drie puntjes ernaast) en kies Aanpassingen wissen — in sommige versies heet dat Resetten. Daarmee verdwijnt het databaserecord en gaat de controle terug naar het bestand op schijf.

Biedt het menu Verwijderen aan in plaats van Aanpassingen wissen of Resetten, dan bestaat dat sjabloon alleen in de database en zit er geen bestand achter. Verwijderen haalt het sjabloon dan volledig weg en WordPress valt verder terug in de hiërarchie.

Vanuit WP-CLI, met een ID uit de lijst hierboven:

wp post delete 482 --force

Wees eerlijk over wat dit kost: aanpassingen wissen gooit definitief weg wat je in de site-editor voor dat sjabloon hebt opgebouwd, en dat kun je niet terugdraaien. Zit er serieus werk in de versie uit de site-editor, kopieer de blokmarkup er dan eerst uit — open het sjabloon in de editor, schakel over naar de codeweergave en plak het resultaat in je .html-bestand. Zo wordt het bestand de bron van waarheid en gaat er niets verloren.

Hoe WordPress een sjabloon kiest

Block themes volgen dezelfde hiërarchielogica als classic themes, alleen met .html-bestanden in templates/ in plaats van .php-bestanden in de hoofdmap van het thema. WordPress loopt van meest specifiek naar minst specifiek en gebruikt het eerste bestand dat bestaat.

Weergave	Volgorde van controleren
Een los bericht	single-post-{slug}.html → single-post.html → single.html → singular.html → index.html
Een pagina	page-{slug}.html → page-{id}.html → page.html → singular.html → index.html
Een categorie-archief	category-{slug}.html → category-{id}.html → category.html → archive.html → index.html
Een custom post type	single-{post-type}.html → single.html → singular.html → index.html
De 404-pagina	404.html → index.html

Twee dingen zetten dit volledig opzij. Ten eerste het databaserecord dat hierboven is beschreven. Ten tweede een sjabloon dat rechtstreeks aan een bericht of pagina is toegewezen — open de berichteditor, zoek het paneel Sjabloon in de zijbalk en kijk of daar iets specifieks is geselecteerd. Een expliciete toewijzing wint altijd van de hiërarchie, en je ziet het niet tenzij je er gericht naar zoekt.

Sjablonen op basis van een slug zijn kwetsbaar op een manier die je je moet inprenten. page-about.html matcht alleen zolang de slug van de pagina about is. Hernoem je de pagina naar about-us, dan houdt het sjabloon op met werken, zonder waarschuwing en zonder foutmelding.

Sjabloon versus sjabloononderdeel

Een sjabloon rendert een volledige weergave en wordt door de hiërarchie gekozen. Een sjabloononderdeel is een fragment — header, footer, sidebar — dat sjablonen binnenhalen. Onderdelen staan in parts/, sjablonen in templates/, en ze worden apart in de database opgeslagen als wp_template_part-records.

De veelvoorkomende verwarring: je past de header aan en de wijziging duikt op pagina’s op waar je hem niet wilde. Dat is correct gedrag. Eén onderdeel wordt gedeeld door elk sjabloon dat het binnenhaalt. Wil je een andere header op één sjabloon, dan heb je een tweede onderdeelbestand nodig én een sjabloon dat daarnaar verwijst — het gedeelde onderdeel aanpassen geeft je nooit variatie per sjabloon.

Het omgekeerde gebeurt ook. Je zet een volledige pagina-indeling in parts/ en vraagt je af waarom de hiërarchie hem nooit oppikt. Onderdelen doen helemaal niet mee in de hiërarchie; er wordt nooit rechtstreeks naartoe gerouteerd.

Bestandsnamen en locatie

Controleer dit voordat je iets exotischers vermoedt:

• De map heet templates/, meervoud, in de hoofdmap van het thema. Niet template/, niet block-templates/. block-templates/ was de juiste naam in het tijdperk van de Gutenberg-plugin, voordat block themes in de kern landden, en veel tutorials tonen het nog steeds — in de huidige WordPress werkt het niet.
• Sjabloononderdelen horen in parts/, niet in template-parts/ (dat is de conventie uit classic themes voor PHP-partials).
• De extensie is .html. Een .php-bestand in templates/ wordt genegeerd.
• Bestandsnamen zijn in kleine letters en gebruiken koppeltekens. single-Post.html of single_post.html matcht niet. Op een hoofdlettersongevoelig bestandssysteem zoals macOS werkt dit lokaal en breekt het op een Linux-server — het klassieke “bij mij werkt het”.
• templates/index.html moet bestaan. Zonder dat bestand ziet WordPress het thema niet als block theme en verschijnt de site-editor mogelijk helemaal niet.
• Werk je in een child theme, dan hebben de sjablonen daarvan voorrang op die van de parent. Een achtergebleven bestand in het child theme wint stilletjes van het parent-bestand dat je zit te bewerken.

Eigen sjablonen die selecteerbaar moeten zijn in de berichteditor moeten daarnaast in theme.json worden aangemeld onder customTemplates, met de basisnaam van het bestand, een leesbare titel en de post types waarvoor het geldt. Zonder die vermelding bestaat het bestand wel, maar verschijnt het nooit in het paneel Sjabloon.

Caching — controleer dit als laatste

Caching is een reëel probleem, maar het is de minst waarschijnlijke oorzaak, en er meteen naar grijpen is hoe mensen een middag verliezen.

Leeg je paginacache en, draai je een persistente objectcache zoals Redis of Memcached, leeg die dan ook — resultaten van sjabloonresolutie kunnen daarin blijven hangen. Laad daarna opnieuw met de browsercache omzeild.

Wat niet helpt: OPcache legen. Block templates zijn .html-bestanden en worden nooit door PHP gecompileerd, dus OPcache heeft er niets mee te maken. Leek OPcache legen dit ooit toch op te lossen, dan is er op datzelfde moment iets anders veranderd.

Nog steeds vast?

Is er geen databaserecord, klopt de bestandsnaam, is er geen sjabloon expliciet aan het bericht toegewezen en zijn de caches al geleegd, kijk dan naar plugins. Alles wat de sjabloonresolutie filtert — een paginabouwer, een membershipplugin, een meertaligheidsplugin, een LMS — kan laat in het verzoek zijn eigen sjabloon ertussen schuiven. Schakel over naar een standaard block theme en test met alle plugins uitgeschakeld, en zet ze daarna één voor één weer aan.

En wordt het sjabloon wel toegepast maar blijft de weergave leeg, dan heb je een ander probleem: controleer of de blokmarkup in het bestand geldig is, want een onjuist blokcommentaar kan ervoor zorgen dat de editor inhoud stilzwijgend weghaalt in plaats van een fout te geven.