Depuis la sortie de WordPress 5.9, construire un thème de blocs n’est plus réservé aux thèmes officiels ou aux early adopters du plugin Gutenberg. La structure s’est stabilisée, la documentation a progressé, et il est désormais tout à fait raisonnable de se lancer sur un projet réel. Ce tutoriel construit, étape par étape, un thème de blocs minimal mais fonctionnel.
L’objectif n’est pas de rivaliser avec la richesse de Twenty Twenty-Two, mais de comprendre chaque brique indispensable : l’arborescence attendue, la syntaxe des fichiers HTML de template, et le rôle de theme.json. Une fois ces bases posées, enrichir le thème devient un exercice largement plus simple.
L’arborescence minimale d’un thème de blocs
Un thème de blocs abandonne le système de templates PHP au profit de fichiers HTML, organisés dans deux dossiers dédiés. Voici la structure minimale à créer à la racine du thème :
style.css: l’en-tête obligatoire, comme pour tout thème WordPress ;theme.json: le fichier de configuration des réglages et styles globaux ;templates/index.html: le template de secours, obligatoire, utilisé quand aucun autre template plus spécifique ne correspond ;templates/single.html: le template utilisé pour l’affichage d’un article ;parts/header.html: la partie d’en-tête, réutilisable entre plusieurs templates ;parts/footer.html: la partie de pied de page, réutilisable de la même façon.
Contrairement aux thèmes PHP classiques, aucun fichier functions.php n’est strictement obligatoire pour démarrer : le minimum viable tient dans ces six fichiers. On y ajoutera du PHP plus tard, uniquement pour des besoins spécifiques (scripts, styles additionnels, blocs personnalisés).
L’en-tête du thème dans style.css
Même sans utiliser réellement ce fichier pour du CSS, WordPress exige toujours un en-tête de commentaire spécifique dans style.css pour reconnaître le thème et l’afficher dans l’administration :
/*
Theme Name: Mon Thème Blocs
Theme URI: https://example.com
Author: Clément Hadrot
Author URI: https://example.com
Description: Un thème de blocs minimal pour apprendre le FSE.
Version: 1.0
Requires at least: 5.9
Requires PHP: 7.4
Text Domain: mon-theme-blocs
*/
Ce fichier peut ensuite accueillir des styles additionnels si besoin, mais la majorité des styles globaux passera désormais par theme.json plutôt que par du CSS classique.
Un theme.json minimal pour démarrer
Pas besoin d’un fichier exhaustif pour commencer : quelques réglages de base suffisent à rendre le thème pleinement fonctionnel dans l’éditeur de site.
{
"version": 2,
"settings": {
"color": {
"palette": [
{
"slug": "fond",
"color": "#ffffff",
"name": "Fond"
},
{
"slug": "texte",
"color": "#1a1a1a",
"name": "Texte"
},
{
"slug": "accent",
"color": "#2563eb",
"name": "Accent"
}
]
},
"layout": {
"contentSize": "700px",
"wideSize": "1100px"
}
},
"styles": {
"color": {
"background": "var(--wp--preset--color--fond)",
"text": "var(--wp--preset--color--texte)"
}
}
}
Notez la valeur "version": 2 : depuis WordPress 5.9, le schéma de theme.json est passé en version 2, avec quelques différences de structure par rapport à la version 1 introduite en 5.8. Un thème créé aujourd’hui doit utiliser cette version la plus récente.
Écrire les template parts
Les template parts sont de simples fichiers HTML contenant des commentaires de blocs Gutenberg, exactement comme le contenu généré par l’éditeur. Voici un en-tête minimal dans parts/header.html :
<!-- wp:group {"tagName":"header","layout":{"type":"constrained"}} -->
<header class="wp-block-group">
<!-- wp:site-title /-->
<!-- wp:navigation {"layout":{"type":"flex","justifyContent":"right"}} /-->
</header>
<!-- /wp:group -->
Et un pied de page dans parts/footer.html :
<!-- wp:group {"tagName":"footer","layout":{"type":"constrained"}} -->
<footer class="wp-block-group">
<!-- wp:paragraph {"align":"center"} -->
<p class="has-text-align-center">© Mon Thème Blocs</p>
<!-- /wp:paragraph -->
</footer>
<!-- /wp:group -->
Ces fichiers ne sont ni plus ni moins que le contenu qu’un bloc core/template-part affichera une fois inséré dans un template. Rien n’empêche d’ailleurs de les créer directement depuis l’éditeur de site, puis de récupérer leur code pour les figer dans ces fichiers du thème.
Assembler le template index.html
Le fichier templates/index.html est le seul strictement obligatoire : c’est le template de secours utilisé quand aucun autre ne correspond au contexte affiché. Il rassemble les template parts et les blocs dynamiques de contenu :
<!-- wp:template-part {"slug":"header","tagName":"header"} /-->
<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
<!-- wp:query {"queryId":1,"query":{"perPage":10,"postType":"post"}} -->
<div class="wp-block-query">
<!-- wp:post-template -->
<!-- wp:post-title {"isLink":true} /-->
<!-- wp:post-excerpt /-->
<!-- /wp:post-template -->
</div>
<!-- /wp:query -->
</main>
<!-- /wp:group -->
<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->
Le bloc core/query remplace ici la boucle WP_Query classique : il affiche une liste d’articles paginée, avec un sous-bloc core/post-template qui répète sa structure pour chaque article trouvé.
Le template single.html pour les articles
Pour l’affichage d’un article individuel, un template plus spécifique prend le pas sur index.html grâce à la hiérarchie de templates que WordPress reconnaît automatiquement d’après son nom de fichier :
<!-- wp:template-part {"slug":"header","tagName":"header"} /-->
<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
<!-- wp:post-title /-->
<!-- wp:post-featured-image /-->
<!-- wp:post-content /-->
</main>
<!-- /wp:group -->
<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->
Cette hiérarchie reprend les principes bien connus du système de templates PHP historique : un fichier nommé exactement comme le contexte concerné (single.html, page.html, archive.html) sera automatiquement privilégié par rapport au template générique index.html.
Activez le thème sur une installation locale jetable avant tout, avec quelques articles de démonstration. Les erreurs de syntaxe dans un fichier HTML de template ne génèrent pas toujours un message d’erreur explicite : mieux vaut repérer les soucis sur un environnement sans conséquence.
En résumé
Construire un thème de blocs minimal ne demande, au fond, pas beaucoup plus de fichiers qu’un thème classique. La vraie différence tient dans la nature du contenu : des commentaires de blocs Gutenberg en HTML plutôt que des appels de fonctions PHP, et un fichier theme.json qui centralise la configuration visuelle.
Une fois cette base posée, les prochaines étapes naturelles consistent à enrichir theme.json avec une échelle typographique complète, ajouter des templates spécifiques pour les pages et les archives, et explorer les patterns de blocs pour proposer des mises en page prêtes à l’emploi. Chaque brique s’appuie sur les mêmes fondations que celles posées dans ce tutoriel.
