Quand vous ouvrez une page WordPress dans le navigateur, une question simple se pose en coulisses : quel fichier PHP du thème va afficher ce contenu ? La réponse ne tient ni au hasard ni à la magie, mais à un algorithme précis que WordPress applique à chaque requête. On appelle cela la hiérarchie de templates, et c’est sans doute la notion la plus structurante à maîtriser quand on développe un thème.
Beaucoup de développeurs débutants copient un thème existant sans comprendre pourquoi tel fichier s’affiche à tel endroit. Résultat : dès qu’il faut personnaliser l’affichage d’une catégorie précise ou d’un type de contenu particulier, c’est la panique. Cet article démonte le mécanisme étape par étape, avec des exemples que vous pourrez reproduire immédiatement dans vos propres projets.
Le principe général : du plus spécifique au plus générique
WordPress fonctionne par élimination. Pour chaque URL visitée, il détermine d’abord le type de contenu demandé (article, page, archive, résultat de recherche, page 404…), puis il parcourt une liste de noms de fichiers possibles, du plus précis au plus vague. Dès qu’il trouve un fichier existant dans le thème actif, il l’utilise et arrête sa recherche.
Cette logique est gérée par la fonction interne template_loader, elle-même appuyée par des fonctions conditionnelles comme is_page(), is_single() ou is_archive(). Vous n’avez pas besoin d’écrire ce code vous-même : il suffit de nommer vos fichiers correctement pour que WordPress les trouve.
Le cas des pages statiques
Prenons l’exemple d’une page WordPress classique, disons une page « Contact » avec le slug contact et l’ID 42. Voici l’ordre exact dans lequel WordPress va chercher un gabarit :
- Un modèle de page personnalisé assigné manuellement dans l’éditeur (via l’en-tête
Template Name) page-contact.php(basé sur le slug)page-42.php(basé sur l’ID)page.php(gabarit générique pour toutes les pages)singular.php(partagé entre pages et articles)index.php(le filet de sécurité universel)
C’est exactement le même principe pour les articles, en remplaçant page par single et en utilisant le post type le cas échéant : single-produit.php pour un article de type produit, par exemple.
Les archives : un cran de complexité supplémentaire
Les pages d’archive (catégories, étiquettes, auteurs, dates, types de contenu personnalisés) suivent une logique similaire, mais avec davantage de granularité. Pour une catégorie de slug actualites et d’ID 7, l’ordre est :
category-actualites.phpcategory-7.phpcategory.phparchive.phpindex.php
Ce schéma se répète pour les étiquettes (tag-*.php), les auteurs (author-*.php) et les types de contenu personnalisés (archive-produit.php). Retenez la logique : slug, puis ID, puis générique du même type, puis générique global, puis index.php.
Cibler précisément avec get_template_part et les templates conditionnels
Au-delà des noms de fichiers automatiques, WordPress propose get_template_part() pour découper vos gabarits en morceaux réutilisables. C’est une pratique que je recommande systématiquement dès qu’un bloc de code se répète entre plusieurs fichiers, comme l’affichage d’une carte d’article.
<?php
// Dans archive.php ou index.php
if ( have_posts() ) :
while ( have_posts() ) :
the_post();
get_template_part( 'template-parts/content', get_post_type() );
endwhile;
endif;
?>Cette ligne va chercher template-parts/content-produit.php si le type de contenu est produit, sinon elle retombe sur template-parts/content.php. C’est une mini hiérarchie de templates à l’intérieur même de votre thème.
Les gabarits spéciaux à ne pas oublier
Certaines situations ont leur propre fichier dédié, en dehors du schéma classique :
front-page.php: prioritaire surhome.phpetpage.phppour la page d’accueil configurée dans les réglages de lecturehome.php: la page listant les derniers articlessearch.php: les résultats de recherche404.php: la page d’erreur, indispensable pour une bonne expérience utilisateur
Un exemple concret de dépannage
Imaginons que vous ayez créé page.php et page-contact.php, mais que la page « Contact » affiche toujours le mauvais design. Le premier réflexe n’est pas de réécrire le code, mais de vérifier l’ordre de priorité : avez-vous, par erreur, assigné un modèle de page personnalisé dans l’éditeur ? Ce choix prend systématiquement le pas sur page-contact.php, même si le fichier existe.
Quand un gabarit ne s’affiche pas comme prévu, je désactive tous les plugins de cache avant de chercher plus loin. La moitié des « bugs de hiérarchie » que je vois sont en réalité des pages mises en cache qui affichent l’ancien template.
En résumé
La hiérarchie de templates n’a rien d’arbitraire : c’est une cascade logique, du plus spécifique au plus générique, qui repose entièrement sur le nommage de vos fichiers PHP. Maîtriser ce mécanisme vous évite d’empiler des conditions if inutiles dans index.php et vous permet de structurer un thème propre, où chaque type de contenu a son fichier dédié. Un seul fichier reste obligatoire pour qu’un thème soit valide : index.php. Tous les autres sont des raffinements optionnels que vous ajoutez au fil de vos besoins.
