Faragiri
Français

Apprendre les thèmes WordPress

La liste que WordPress parcourt pour choisir un gabarit, les deux formats de thème et la façon de les distinguer, et pourquoi éditer le bon fichier ne suffit pas toujours.

6Sections
4Min de lecture
5Profondeur

Une URL, cinq candidats

L'ordre dans lequel WordPress essaie les fichiers pour un article seul

Le premier fichier qui existe gagne et les autres ne sont jamais consultés, ce qui explique pourquoi ajouter un fichier change le rendu et modifier le mauvais ne change rien.

  1. single-{post_type}-{slug}.phpUn seul article précis. Invisible dès que le slug change
  2. single-{post_type}.phpTout article d'un même type. La substitution la plus utile
  3. single.phpTout article seul, quel que soit le type
  4. singular.phpPartagé avec les pages. Le fichier que la plupart des thèmes devraient avoir
  5. index.phpExiste toujours, car un thème sans lui n'en est pas un

Un thème de blocs parcourt la même liste avec des fichiers .html dans un dossier templates. Le rail est la hiérarchie, pas le format du fichier, ce qui explique qu'un tutoriel sur un format s'applique presque toujours à l'autre.

WordPress choisit un fichier de gabarit en essayant une liste dans l'ordre et en prenant le premier qui existe. Pour un article seul, la liste est single-{post_type}-{slug}.php, puis single-{post_type}.php, puis single.php, puis singular.php, puis index.php. Rien n'est déclaré nulle part, le nom du fichier est la seule route.

Ce qui veut dire qu'index.php est le seul fichier qu'un thème exige réellement, avec style.css pour l'en-tête qui le nomme. Chaque autre fichier intercepte la liste plus tôt, et en ajouter un est la façon de faire différer un seul type de contenu sans toucher à ce qui fonctionne déjà.

Les listes à connaître par cœur

  • Une page : {custom}.php depuis le réglage de gabarit propre à la page, puis page-{slug}.php, page-{id}.php, page.php, singular.php, index.php
  • Une archive : archive-{post_type}.php, puis archive.php, puis index.php
  • Une page absente : 404.php, puis index.php
  • singular.php est le repli partagé entre un article seul et une page, et c'est le fichier que la plupart des thèmes devraient avoir et n'ont pas

Les variantes par identifiant en haut de liste sont la sortie de secours, et il vaut mieux s'en servir rarement : un gabarit nommé d'après l'identifiant d'une page devient invisible le jour où quelqu'un renomme la page, et l'apparence revient alors en arrière sans qu'on comprenne pourquoi.

Deux faits qui achèvent le modèle

Un fichier de gabarit est inclus, pas appelé, donc tout ce qui est déjà en portée à ce moment est disponible : $post, la requête, et tout ce qu'une extension a préparé sur un crochet précédent. Et la boucle est explicite plutôt qu'implicite, ce qui explique qu'un gabarit qui oublie the_post() affiche le même article en boucle ou rien du tout.

Les morceaux qu'un gabarit assemble sont des fichiers séparés atteints avec get_header(), get_footer() et get_template_part('content', get_post_type()). Ce dernier applique le même principe de repli un niveau plus bas, cherchant content-post.php et se contentant de content.php, ce qui permet à un thème de rester court sans qu'aucun de ses fichiers ne connaisse les autres.

Ce qui bloque un lecteur francophone avant même le code

La hiérarchie de gabarits n'a pas de traduction, et c'est la première chose à admettre plutôt qu'à contourner. Les noms de fonction, les messages d'erreur et la documentation officielle sont en anglais, et un développeur qui lit mal l'anglais technique résout deux problèmes à la fois en croyant n'en résoudre qu'un. Lire une trace d'erreur en anglais est un exercice plus petit qu'apprendre l'anglais entier, et un modèle de langage explique aujourd'hui une trace en français mieux qu'une recherche sur un forum.

Deux formats de thème, et comment les reconnaître d'un coup d'œil

Un thème classique est fait de gabarits PHP plus functions.php, et la hiérarchie ci-dessus est tout le modèle de routage. Un thème de blocs est fait de fichiers HTML dans un dossier templates/ plus un theme.json, modifié dans l'éditeur de site plutôt que dans un fichier, et la hiérarchie s'applique encore avec .html à la place de .php.

Le repère tient en une seule liste de dossier : theme.json et templates/index.html présents veulent dire thème de blocs, seulement index.php et functions.php veut dire thème classique. Un studio parisien qui livre un site vitrine ancien sur un thème classique et le migre vers un thème de blocs découvre souvent, à ce moment précis, que la moitié des gabarits personnalisés du client n'ont pas d'équivalent direct.

Les outils à faire tourner en 2026

Un thème enfant est l'outil quand le thème appartient à quelqu'un d'autre, gratuit avec WordPress : un dossier avec un style.css qui nomme le parent et un functions.php, et tout fichier de gabarit ajouté prend le dessus sur la version du parent. Il a remplacé la modification du parent, défaite par la mise à jour suivante, et c'est la convention WordPress la plus utile qui existe.

Query Monitor nomme le gabarit réellement utilisé pour la requête en cours, gratuit et open source, ce qui transforme la liste ci-dessus en simple observation. Il a remplacé l'ajout d'un echo dans chaque fichier candidat pour découvrir lequel tournait, et il nomme aussi le dossier parent ou enfant d'où le gabarit vient.

Là où ça bloque

Le blocage est de modifier un fichier qui n'est pas celui utilisé. Un changement dans single.php ne fait rien parce qu'un single-post.php existe, ou parce que le thème est un thème enfant et que le fichier modifié est celui du parent. Rien ne signale d'erreur, le changement n'a simplement aucun effet, et la réaction naturelle est de faire un changement plus gros encore.

Avant de modifier quoi que ce soit, lire quel gabarit sert la page visée. C'est une ligne dans Query Monitor et elle supprime toute cette catégorie de problème. Ce que les gabarits appellent en retour est le sujet des extensions WordPress, et le langage dans lequel tout cela s'écrit est celui des bases de PHP.

À côté

Au-dessus