Le theme.json est le fichier le plus important des thèmes modernes WordPress, car c’est via celui-ci que l’on va configurer notre design system dans l’éditeur, à savoir les couleurs, polices, espacements… Il va également nous permettre d’activer ou désactiver des fonctionnalités de l’éditeur, et définir les styles par défaut du site.
Sommaire du cours
La création d’un site avec le Full Site Editing commence avec le theme.json
, du moins pour les développeurs et les low-codeurs.
Ce fichier vous permet de déclarer un bon nombre d’informations comme les couleurs, espacements, tailles, typos… à propos de votre thème à l’aide de clés et valeurs.
On retrouve en substance tous les réglages que l’on peut faire via l’éditeur de site.
Voici un exemple avec le réglage de largeur des contenus. Depuis l’éditeur cela ressemble à ceci :

Et dans le theme.json
, ça ressemble plutôt à cela :
Mais en réalité, il va bien plus loin que l’interface visuelle, il permet notamment d’activer ou désactiver certaines fonctionnalités de l’éditeur. Et ça, on ne peut pas le faire autrement qu’en modifiant le fichier theme.json
.
En tant que développeurs, on va donc privilégier cette approche. On pourra ainsi versionner toutes nos configurations avec git.
Aparté: Le format JSON
Le format JSON est un des formats de données les plus en vogue du moment. C’est d’ailleurs le format de référence des API REST.
Il fonctionne par clés / valeurs et contrairement à un objet JavasScript, il faut que chaque clé soit entre guillemets. Exemple : "clé" : "valeur"
.
Les valeurs de type numériques ou booléennes n’ont quant à elles pas besoin de guillemets. Exemple : "fontWeight" : 500
ou "defaultPalette" : true
.
Pensez à la virgule en fin de ligne, à part si vous êtes sur la dernière instruction. Et voilà, vous savez faire du JSON !
Anatomie du theme.json
Si vous prenez un thème tout fait (comme Ollie ou le thème par défaut de WP) et que vous ouvrez le fichier theme.json
, vous pourriez vous faire une petite frayeur devant parfois plus de 1000 lignes.
Mais ne vous inquiétez pas, on va découper et se concentrer sur un concept à la fois dans chacun des cours de ce chapitre.
Et on va d’abord commencer par comprendre la structure globale de ce fichier :
Si je me cantonne uniquement aux éléments de premier niveau, on obtient ceci :
$schema
: C’est la nomenclature qui contraint les valeurs possibles du fichier ;version
: Le numéro de version du schéma ;settings
: Ici on va définir nos valeurs globales et les fonctionnalités de l’éditeur ;styles
: Pour appliquer nos styles par défaut aux titres, textes, et blocs ;customTemplates
: Pour déclarer des modèles sur-mesure en plus des existants ;templateParts
: Nous permet de déclarer l’en-tête, le pied de page et la sidebar ;patterns
: Ajouter des compositions du répertoire officiel de WordPress.
On va profiter de ce cours pour aller un peu plus dans les détails.
Pour connaître l’intégralité des possibilités offertes par le theme.json
, vous pouvez vous référer à la documentation officielle :
Des nouveautés sont ajoutées à chaque nouvelle version de WordPress. Ça bouge encore beaucoup de ce côté là, alors n’hésitez pas à consulter la documentation régulièrement pour ne rien rater.
Les différentes sections du theme.json
Allez, maintenant on va aller voir ce qu’il se passe dans chacune des sections du theme.json
.
Ce sera bien plus facile de modifier ce fichier des enfers une fois que vous aurez retenu à quoi sert chaque section.
Car pour ne rien arranger, on retrouvera souvent des sous-sections portant des noms similaires à d’autres endroits du fichier. Du coup, les premiers temps seront un peu difficiles, mais ne vous inquiétez pas, vous serez très bientôt un expert.
Le schéma de standardisation et la version
On commence avec le schéma. On va systématiquement le mettre dans notre fichier car ça permettra à notre éditeur de code de vérifier que ce que l’on écrira par la suite sera conforme à ce schéma.
Si ce n’est pas le cas, votre éditeur vous le signalera. Par exemple, j’ai tenté d’ajouter la clé core
dans mon fichier, et VS Code me souligne la ligne qui ne lui convient pas :

De cette manière, vous saurez immédiatement si ce que vous ajoutez à votre theme.json
est valide ou non.
De plus, votre éditeur sera capable de vous suggérer les valeurs possibles lors de l’écriture du fichier. C’est encore plus pratique pour ne pas se tromper :

Dans cet exemple, VS Code me suggère les valeurs possibles à l’intérieur de Settings > Typography.
Bien sûr, le schéma va évoluer avec le temps. WordPress proposera des nouveautés, mais aussi des changements structurels. C’est pour cela que vous allez également indiquer le numéro de version du schéma à suivre.
À l’heure où j’écris ces lignes, on est à la version 3
. Pensez à consulter la documentation du theme.json à chaque début de projet pour connaître la version la plus récente.
Vous pouvez également consulter la documentation du schema actuel sur wordpress.org.
Settings
Cette partie est probablement la plus importante de ce theme.json
, car c’est ici qu’on va configurer les 2 choses les plus importantes pour notre site :
- Les styles globaux tout d’abord : couleurs, typographies, espacements…
- Mais également les fonctionnalités à activer ou désactiver dans Gutenberg.
Voici un exemple concernant les couleurs :
Comme vous pouvez le voir, sous color
on va avoir des instructions booléennes permettant d’activer ou de désactiver les options de couleur dans l’éditeur Gutenberg.
Ensuite, on déclare la liste des couleurs de la palette que l’on va proposer sur le site.
Voici ce que ça donnera dans l’éditeur de WordPress :

À gauche, c’est si je passe toutes les valeurs à true
, et à droite, si je passe tout à false
. C’est un bel exemple du contrôle qu’on peut avoir sur Gutenberg, n’est-ce pas ?
Dans les prochains cours, on passera en revue tous les réglages disponibles afin de bien comprendre l’objectif de chaque valeur.
Styles
Les éléments de notre charte graphique que nous avons configurés dans settings
seront disponibles dans l’éditeur.
Mais on va également pouvoir appliquer ces styles globalement aux différents éléments du site grâce à la section styles
du fichier JSON.
Voici à quoi ça ressemble :
Chaque section permet de définir un élément bien précis :
color
: Les couleurs des textes, liens, du fond ;spacing
: L’espacement par défaut entre les blocs, et dans les blocs ;typography
: La police des titres et celle des textes ;elements
: Les styles des éléments primitifs : boutons, niveaux de titres, survol ;blocks
: Les styles par défaut à appliquer pour chaque bloc de l’éditeur.
Les valeurs qu’on a définies précédemment sont désormais disponibles au travers de variables CSS, avec des noms parfois un peu longs.
Voici un exemple avec les couleurs globales du site :
Dans cet exemple, on applique notre couleur primaire à tous les textes, et la couleur blanche sur le fond du site. Ce ne sera donc pas nécessaire de le faire en CSS.
Si on veut maintenant définir une couleur spécifique à la balise <h2>
, ce sera dans elements > h2 > color.
Vous allez voir que c’est une sacré gymnastique au début de trouver le bon endroit pour définir les styles d’un élément. Mais pas d’inquiétude, on y reviendra dans les prochains cours.
Nommage des valeurs globales CSS dans le theme.json
Revenons pour le moment sur les valeurs globales. Leur nom est un peu long, et un peu indigeste au début, je ne vous le cache pas. Mais on prend vite l’habitude, promis !
Voici l’anatomie d’une valeur générée par wordPress :

Décortiquons ce nommage bien singulier :
- La première partie
var:
indique qu’on souhaite utiliser une valeur globale ; - La seconde partie est le type, il peut-être
preset
oucustom
; - La troisième représente la propriété :
color
,font-size
,spacing
… - Et la dernière partie représente la valeur configurée en JSON :
primary
,s
,m
…
Je n’entre pas encore dans les détails, on abordera le sujet dans un cours séparé. Pour le moment, l’objectif est que vous commenciez à prendre vos repères dans ce fichier theme.json
.
Custom templates
Désormais, les modèles de page sur-mesure devront être déclarés dans le theme.json
, sous la section customTemplates
:
Un exemple récurrent est de créer un modèle de page en pleine largeur, sans le titre principal, pour créer toutes vos landing pages du site.
Le modèle de page « standard » pourra être réservé aux pages de contenus comme les mentions légales, avec le titre et une zone de contenu étroite.
Avant, on déclarait les modèles directement en PHP, mais ce n’est plus valable comme nos modèles sont désormais en HTML.
Templates parts
Les template parts sont des morceaux de template, destinés à être réutilisés sur le site. Mais outre l’en-tête, le pied de page et éventuellement une sidebar, on va plutôt désormais utiliser les compositions.
Donc en général, cette partie du theme.json
ne va pas trop changer.
Patterns
Et enfin, cette section permet de déclarer les compositions que l’on veut récupérer depuis wp.org.
En effet, il existe un répertoire de compositions créées par la communauté, un peu comme le répertoire des extensions.

Il suffit de récupérer le slug de chaque composition depuis l’URL et de les ajouter à votre fichier JSON :
Il sera plus judicieux de créer les vôtre. On verra plus tard dans la formation comment désactiver les suggestions de compositions depuis l’éditeur.
Configuration via l’éditeur de WordPress et export
L’éditeur de WordPress permet de gérer visuellement la plupart de ces réglages. Vous pourriez donc, au lieu d’écrire le JSON passer par l’interface du Full Site Editing :

Ensuite, il vous suffira d’exporter votre thème, car WordPress propose justement une option pour cela.
Cliquez sur les 3 points en haut à droite de l’interface et choisissez « Exportation ».

Cela aura pour effet de générer un zip contenant votre thème personnalisé. Vous pourrez ainsi récupérer le theme.json
, mais aussi les compositions et modèles de pages en HTML !
Aparté: Comment c’est enregistré en base ?
Les réglages que vous faites depuis l’éditeur sont enregistrés en base de données dans la table wp_posts
, sous forme d’un objet JSON sérialisé, dans un Custom Post Type privé wp_global_styles
spécialement prévu pour les données du FSE.
D’un point de vue purement développeur, il y a moyen que vous ne trouviez pas ça fou. C’est pas dingue, mais ça fonctionne bien au final.
Lorsque vous faites un thème sur mesure, les données du JSON sont chargées par défaut, mais si elles sont surchargées, ce sont les données de la base qui feront foi.
On reparlera de cette problématique vers la fin de la formation.
Les limites de l’éditeur visuel
Par contre, en utilisant l’éditeur, vous n’aurez pas autant de possibilités qu’en modifiant le JSON. Il manque notamment :
- L’activation et la désactivation de réglages et de fonctionnalités de l’éditeur.
- La gestion des espacements.
- La gestion de valeurs personnalisées, comme les arrondis.
Il y a quelques temps, il manquait la gestion des ombres, mais elle a été ajoutée avec l’arrivée de WordPress 6.6.
Dans un futur proche, il ne manquera probablement plus rien. Mais pour le moment, on est encore obligé de passer par le theme.json
.
Maintenant que vous connaissez les bases du fichier theme.json
, on va aller explorer les possibilités afin de trouver les plus intéressantes pour concevoir efficacement nos sites.
Dans le prochain cours, on va explorer les fonctionnalités que l’on peut activer et désactiver dans Gutenberg.
Mathieu Godard
Le 2 décembre 2024
Salut ! Le numéro de version est-il lié au changement de version de WordPress ? J’aurais tendance à dire oui mais j’aimerais être sûr. Merci 🙂
Maxime BJ
Le 2 décembre 2024
Non c’est un versionnement à part entière lié au fichier et à ses propriétés : en cas de changement de structure, il y aura un changement de version pour que WordPress sache comment interpréter ton fichier.
Mathieu Godard
Le 7 décembre 2024
Pardon pour le manque de précision, je parlais de la version du schéma : sans pour autant être le même numéro que la version de WordPress, est-il incrémenté à chaque nouvelle version majeure de WordPress (6.6, 6.7, …) ?
Maxime BJ
Le 7 décembre 2024
Oui moi aussi. C’est le numéro de version du schéma. Tant que la structure ne change pas fondamentalement, on sera en version 3. De nouvelles propriétés pourront être ajoutées en version 3. Par contre, s’il y a un changement de clés ou de structure, on passera en version 4.
Mathieu Godard
Le 18 décembre 2024
La version du schéma semble plutôt consultable sur cette page : https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-living/
Maxime BJ
Le 18 décembre 2024
Je rajoute le lien dans le cours, merci !
Mathieu Godard
Le 7 décembre 2024
Merci pour ta réactivité 🙂