Pourquoi mon template bloc ne s'applique-t-il pas dans WordPress ?

En général parce qu'une copie enregistrée en base de données écrase le fichier. Dès que vous modifiez un template dans l'éditeur de site et que vous cliquez sur Enregistrer, WordPress crée un article wp_template et le sert à la place du fichier .html de votre dossier de thème. Toute modification du fichier après ce moment reste invisible côté visiteur.

Comment forcer WordPress à utiliser mon fichier de thème plutôt que la version de l'éditeur de site ?

Ouvrez Apparence puis Éditeur puis Templates, repérez le template, et utilisez son menu d'options pour effacer les personnalisations ou le réinitialiser. Cela supprime l'enregistrement en base et rend la main au fichier sur le disque. Si le menu propose Supprimer plutôt que Réinitialiser, le template n'existe qu'en base de données et n'a aucun fichier derrière lui.

Où placer les fichiers de template bloc dans un thème WordPress ?

Les templates complets vont dans un dossier templates à la racine du thème, et les sections réutilisables dans un dossier parts. Les deux utilisent l'extension .html, des noms de fichiers en minuscules, et des tirets plutôt que des tirets bas. Un thème bloc exige aussi que templates/index.html existe, sinon WordPress ne le considère pas du tout comme un thème bloc.

Quelle est la différence entre un template et une partie de template ?

Un template rend une page entière et est choisi par la hiérarchie de templates selon ce qui est affiché. Une partie de template est un fragment, comme un en-tête ou un pied de page, qu'un template intègre. Modifier la partie en-tête change tous les templates qui l'incluent, ce qui explique pourquoi les modifications de parties semblent souvent s'être appliquées au mauvais endroit.

Le cache peut-il empêcher la mise à jour des templates bloc ?

Parfois, mais c'est la cause la moins probable et elle doit être vérifiée en dernier. Les caches de page et les caches d'objets persistants peuvent conserver un balisage périmé : videz les deux avant de conclure. Vider OPcache ne sert à rien ici, car les templates bloc sont des fichiers .html qui ne sont jamais compilés par PHP.

Pourquoi mon template basé sur le slug d'une page a-t-il cessé de fonctionner ?

Les templates basés sur le slug sont comparés au slug de l'article courant au moment de la requête. Renommer une page change son slug, donc page-about.html cesse silencieusement de correspondre dès que la page devient about-us. Cela vaut aussi pour les templates de catégorie et d'étiquette. Renommez le fichier pour qu'il corresponde au nouveau slug, ou affectez explicitement le template dans la barre latérale de l'éditeur de contenu.

Template bloc WordPress qui ne s'applique pas ? Commencez par la base de données

Votre fichier de template est presque certainement ignoré parce qu’une copie en base de données l’emporte. Dès l’instant où vous ouvrez un template dans l’éditeur de site et appuyez sur Enregistrer, WordPress écrit un article wp_template, et à partir de là c’est cet enregistrement qui est servi à la place du fichier .html de votre dossier de thème — si bien que chaque modification apportée ensuite au fichier reste invisible côté visiteur. Effacer cet enregistrement, c’est la solution, et c’est la première chose à vérifier avant de toucher à la hiérarchie, au nom du fichier ou au cache.

Confirmez que la copie en base existe

Allez dans Apparence → Éditeur → Templates. Tout template que WordPress sert depuis la base est signalé dans la liste — selon votre version de WordPress, le badge indique « Personnalisé » ou le template apparaît sous un filtre « Personnalisé ». Ce badge est toute la réponse. S’il est là, votre fichier n’est pas utilisé.

Vous pouvez vérifier la même chose en ligne de commande, c’est plus rapide et cela fonctionne même quand l’éditeur de site fait des siennes :

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

Chaque ligne est une surcharge en base de données. Le post_name correspond au slug du template : une ligne nommée single masque donc templates/single.html.

Un détail qui piège tout le monde : ces enregistrements sont rattachés à un thème par un terme de taxonomie, pas par un chemin. Si vous renommez le dossier de votre thème, les templates enregistrés restent en base mais cessent de correspondre au thème actif, et le site bascule brutalement sur les fichiers. Cela ressemble à « mes personnalisations ont disparu » plutôt qu’à « mon fichier est ignoré » — même mécanisme, symptôme inverse.

Effacez-la

Dans l’éditeur de site, ouvrez le menu d’options du template (les trois points à côté) et choisissez Effacer les personnalisations — certaines versions l’intitulent Réinitialiser. Cela supprime l’enregistrement en base et la main revient au fichier sur le disque.

Si le menu propose Supprimer au lieu d’Effacer les personnalisations ou de Réinitialiser, c’est que ce template existe uniquement en base de données et n’a aucun fichier derrière lui. Le supprimer retire complètement le template et WordPress redescend la hiérarchie.

Depuis WP-CLI, avec un identifiant issu de la liste ci-dessus :

wp post delete 482 --force

Soyez lucide sur le coût : effacer les personnalisations supprime définitivement tout ce que vous aviez construit dans l’éditeur de site pour ce template, et c’est irréversible. Si la version de l’éditeur de site contient du vrai travail, copiez d’abord le balisage de blocs — ouvrez le template dans l’éditeur, basculez en vue code, et collez le résultat dans votre fichier .html. Ainsi le fichier redevient la source de vérité et rien n’est perdu.

Comment WordPress choisit un template

Les thèmes bloc utilisent la même logique de hiérarchie que les thèmes classiques, simplement avec des fichiers .html dans templates/ au lieu de fichiers .php à la racine du thème. WordPress parcourt du plus spécifique au moins spécifique et utilise le premier fichier existant.

Ce qui est affiché	Ordre de vérification
Un article	`single-post-{slug}.html` → `single-post.html` → `single.html` → `singular.html` → `index.html`
Une page	`page-{slug}.html` → `page-{id}.html` → `page.html` → `singular.html` → `index.html`
Une archive de catégorie	`category-{slug}.html` → `category-{id}.html` → `category.html` → `archive.html` → `index.html`
Un type de contenu personnalisé	`single-{post-type}.html` → `single.html` → `singular.html` → `index.html`
La page 404	`404.html` → `index.html`

Deux choses court-circuitent complètement tout cela. D’abord, l’enregistrement en base décrit plus haut. Ensuite, un template affecté directement à un article ou à une page — ouvrez l’éditeur de contenu, cherchez le panneau Modèle dans la barre latérale, et vérifiez si quelque chose de précis y est sélectionné. Une affectation explicite bat la hiérarchie à tous les coups, et elle est invisible tant qu’on ne va pas la chercher.

Les templates basés sur le slug sont fragiles d’une manière qu’il vaut mieux intégrer une bonne fois. page-about.html ne correspond que tant que le slug de la page est about. Renommez la page en about-us et le template cesse de s’appliquer, sans avertissement et sans erreur.

Template contre partie de template

Un template rend une vue entière et est sélectionné par la hiérarchie. Une partie de template est un fragment — en-tête, pied de page, colonne latérale — que les templates intègrent. Les parties vivent dans parts/, les templates dans templates/, et elles sont stockées séparément en base sous forme d’enregistrements wp_template_part.

La confusion classique : vous modifiez l’en-tête, et le changement apparaît sur des pages que vous ne vouliez pas toucher. C’est le comportement correct. Une même partie est partagée par tous les templates qui l’incluent. Si vous voulez un en-tête différent sur un seul template, il vous faut un second fichier de partie et un template qui le référence — modifier la partie partagée ne vous donnera jamais de variation par template.

L’inverse arrive aussi. Vous placez une mise en page complète dans parts/ et vous vous demandez pourquoi la hiérarchie ne la prend jamais. Les parties ne sont tout simplement pas candidates dans la hiérarchie ; rien n’y sera jamais routé directement.

Nommage et emplacement des fichiers

Vérifiez ceci avant de supposer quoi que ce soit de plus exotique :

Le dossier s’appelle templates/, au pluriel, à la racine du thème. Pas template/, pas block-templates/. block-templates/ était le nom correct à l’époque de l’extension Gutenberg, avant l’arrivée des thèmes bloc dans le cœur, et beaucoup de tutoriels le montrent encore — cela ne fonctionne pas avec les versions actuelles de WordPress.
Les parties de template vont dans parts/, pas dans template-parts/ (qui est la convention des thèmes classiques pour les fragments PHP).
L’extension est .html. Un fichier .php dans templates/ est ignoré.
Les noms de fichiers sont en minuscules et utilisent des tirets. single-Post.html ou single_post.html ne correspondront à rien. Sur un système de fichiers insensible à la casse comme macOS, cela fonctionne en local et casse sur un serveur Linux — le grand classique du « ça marche sur ma machine ».
templates/index.html doit exister. Sans lui, WordPress ne classe pas le thème comme thème bloc et l’éditeur de site peut ne pas apparaître du tout.
Si vous travaillez dans un thème enfant, ses templates sont prioritaires sur ceux du parent. Un fichier oublié dans le thème enfant battra silencieusement le fichier parent que vous êtes en train de modifier.

Les templates personnalisés qui doivent être sélectionnables dans l’éditeur de contenu doivent aussi être déclarés dans theme.json sous customTemplates, avec le nom de base du fichier, un titre lisible et les types de contenu concernés. Sans cette entrée, le fichier existe mais n’apparaît jamais dans le panneau Modèle.

Le cache — à vérifier en dernier

Le cache est un vrai sujet, mais c’est la cause la moins probable, et commencer par là est le meilleur moyen de perdre un après-midi.

Videz votre cache de page et, si vous utilisez un cache d’objets persistant comme Redis ou Memcached, videz-le aussi : les résultats de résolution de template peuvent y être conservés. Rechargez ensuite en contournant le cache du navigateur.

Ce qui ne servira à rien : vider OPcache. Les templates bloc sont des fichiers .html qui ne sont jamais compilés par PHP, donc OPcache n’a rien à voir avec eux. Si vider OPcache a semblé régler le problème une fois, c’est qu’autre chose avait changé au même moment.

Toujours bloqué ?

Sans enregistrement en base, avec un nom de fichier correct, sans affectation explicite de template sur l’article et avec les caches déjà vidés, regardez du côté des extensions. Tout ce qui filtre la résolution de template — un constructeur de pages, une extension d’adhésion, une extension multilingue, un LMS — peut substituer son propre template tard dans la requête. Basculez sur un thème bloc par défaut et testez avec les extensions désactivées, puis réactivez-les une par une.

Et si le template s’applique bien mais rend une page vide, c’est un autre problème : vérifiez que le balisage de blocs du fichier est valide, car un commentaire de bloc mal formé peut amener l’éditeur à retirer le contenu silencieusement plutôt qu’à lever une erreur.