# Hiérarchie des archives de types personnalisés dans un thème bloc

> Pourquoi un fichier archive-produit.html n'est jamais utilisé dans un thème bloc, et comment WordPress retombe finalement sur index.html.

- Auteur : Clément Hadrot
- Publié le : 2021-06-15
- Mis à jour le : 2021-06-15
- Catégorie : FSE
- URL : https://wpmoderne.dev.wordpress-developpement.fr/fse/hierarchie-archives-types-personnalises-theme-bloc/

## L’essentiel

- Nom de fichier calqué sur la hiérarchie PHP classique
- Résolution jusqu'à archive.html puis index.html
- Encore expérimental via le plugin Gutenberg avant WordPress 5.9

« 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.

> L'essentiel à retenir : Nom de fichier calqué sur la hiérarchie PHP classique ; Résolution jusqu'à archive.html puis index.html ; Encore expérimental via le plugin Gutenberg avant WordPress 5.9

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 `templates` du 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.