« Mon fichier archive-produit.html ne sert à rien, WordPress affiche toujours le même gabarit générique. » Ce constat, un développeur me l’a partagé après plusieurs heures perdues sur un thème expérimental testé avec le plugin Gutenberg, en amont de la future version stable de l’éditeur de site. Le problème ne venait pas d’un bug, mais d’une incompréhension de la hiérarchie de résolution des templates dans ce nouveau modèle.
Cette hiérarchie reprend l’esprit de celle des thèmes PHP classiques, documentée depuis des années dans le Codex puis le Manuel du développeur de thèmes, mais elle repose désormais sur des fichiers HTML annotés de blocs, rangés dans un dossier templates à la racine du thème.
Ce que WordPress cherche réellement
Pour l’archive d’un type de contenu personnalisé nommé produit, la hiérarchie tente d’abord de charger archive-produit.html. Si ce fichier n’existe pas dans le dossier templates du thème, WordPress retombe sur archive.html, un gabarit générique pour toutes les archives, quel que soit le type de contenu concerné.
Si ce fichier générique n’existe pas non plus, c’est index.html qui prend le relais, en dernier recours absolu. Dans un thème bloc minimaliste, il n’est pas rare que seul ce fichier index.html existe, ce qui explique pourquoi toutes les archives, quel que soit leur type, affichent alors un rendu strictement identique.
Le piège qui a coûté plusieurs heures sur ce projet
Le développeur avait bien créé archive-produit.html, mais dans un sous-dossier templates/archives/ au lieu de la racine attendue templates/. La hiérarchie de résolution ne cherche que dans l’emplacement exact prévu, sans tolérance sur l’arborescence interne, contrairement à certaines habitudes prises avec des thèmes PHP plus permissifs sur l’organisation des fichiers.
Une fois le fichier déplacé au bon endroit, l’archive du type produit a immédiatement chargé son propre gabarit, sans aucune autre modification de code. La leçon à retenir : dans un thème bloc, la structure de dossier n’est pas une convention flexible, elle fait partie intégrante du contrat de nommage.
Comment vérifier soi-même la résolution appliquée
- Lister précisément les fichiers présents dans le dossier
templatesdu thème actif, sans se fier à sa mémoire du projet. - Confirmer le nom exact du type de contenu personnalisé enregistré via
register_post_type(), notamment le paramètre du slug utilisé dans les URL. - Tester en renommant temporairement un fichier suspecté pour observer si le rendu change, méthode rustique mais souvent la plus rapide pour confirmer une hypothèse.
Ce dernier point de méthode reste, à ce stade expérimental du plugin Gutenberg, plus fiable que la documentation elle-même, encore incomplète sur certains cas limites liés aux types personnalisés.
Ce qui diffère vraiment de la hiérarchie PHP classique
La logique générale reste très proche de celle popularisée par le Codex WordPress depuis des années : du plus spécifique au plus générique. La vraie différence tient à l’absence, pour l’instant, d’équivalent du fichier archive-{post_type}-{slug}.php ultra spécifique que certains thèmes PHP avancés exploitaient pour un rendu par article isolé au sein d’une archive.
Comprendre une hiérarchie de résolution demande de l’observer patiemment, pas de la deviner à partir de souvenirs d’un système voisin, même proche.
Pour aller plus loin
Cette mécanique, encore mouvante avant la stabilisation prévue de l’éditeur de site dans le cœur de WordPress, mérite d’être testée sur un environnement de développement dédié avant tout projet client. Je recommande de documenter, pour chaque thème bloc construit, la liste exacte des fichiers de templates présents et leur rôle, un réflexe qui manque encore cruellement à beaucoup d’équipes découvrant ce modèle.
La prochaine étape logique de cette exploration portera sur la hiérarchie propre aux archives de taxonomie, sensiblement différente, que je traiterai séparément tant les subtilités méritent leur propre attention.
