Créer un thème de blocs FSE WordPress pas à pas

📍 Guide principal : Développement WordPress : plugins, thèmes et blocs. Ce tutoriel clôt la série en habillant le projet.

Introduction

Votre annuaire vit en base, s’affiche dans un bloc, s’expose en API. Il lui manque un habillage : une présentation cohérente pour le visiteur. Pendant quinze ans, cela voulait dire écrire des gabarits en PHP. Depuis WordPress 5.9, une autre voie existe — l’édition complète du site, ou Full Site Editing (FSE), consolidée au fil des versions 6.x. Un thème de blocs ne contient plus de PHP de gabarit : ses pages sont décrites en HTML de blocs, et toute son apparence — couleurs, typographie, espacements — est centralisée dans un unique fichier, theme.json. Le thème devient un système de design déclaratif que l’on modifie en grande partie depuis l’interface. À la fin de ce tutoriel, Annuaire Quartier disposera d’un thème de blocs minimal mais réel, avec une page dédiée à la fiche d’un artisan.

🎯 Ce que vous allez apprendre

• Connaître les fichiers indispensables d’un thème de blocs.
• Configurer couleurs, typographie et espacements dans theme.json.
• Écrire des gabarits en HTML de blocs et les découper en parties réutilisables.
• Créer un gabarit dédié au type « artisan ».
• Éditer le thème depuis l’interface sans toucher au code.

🛠️ Ce que vous allez construire

Un dossier de thème annuaire-theme/ avec sa configuration theme.json, un gabarit d’accueil, un en-tête et un pied de page réutilisables, et un gabarit single pour afficher une fiche d’artisan avec son téléphone et son quartier. Le tout modifiable depuis l’éditeur de site, sans rouvrir un fichier.

Prérequis

• WordPress 7.0 ou récent (le thème.json version 3 demande au moins la 6.6).
• Le type « artisan » en place (voir types de contenu et métadonnées) et quelques fiches.
• Des notions de HTML ; aucune connaissance de PHP de gabarit n’est requise.
• Test express : si vous savez créer un dossier et y déposer des fichiers texte, vous pouvez construire un thème de blocs.
• ⏱️ Temps estimé : ~50 minutes.

Le modèle mental : un thème déclaratif

Un thème classique mélangeait logique (PHP) et présentation dans chaque gabarit. Un thème de blocs sépare les rôles. La configuration globale — la palette, les polices, l’échelle d’espacement — vit dans theme.json, en un seul endroit, sous forme de données. La structure des pages vit dans des fichiers .html remplis de balisage de blocs. Il n’y a plus de boucle PHP à écrire : WordPress sait afficher le contenu à partir des blocs déclarés. Ce déplacement du code vers la donnée est ce qui rend le thème éditable depuis l’interface : changer une couleur dans theme.json ou dans l’éditeur de site revient au même, car les deux écrivent la même donnée.

Étape 1 — Les fichiers indispensables

Un thème de blocs valide tient à trois fichiers. style.css porte l’en-tête qui identifie le thème (comme l’en-tête d’une extension). theme.json porte la configuration. Et templates/index.html est le gabarit minimal obligatoire, celui que WordPress utilise par défaut. On crée donc wp-content/themes/annuaire-theme/ avec cette ossature.

annuaire-theme/
├── style.css            (en-tête du thème)
├── theme.json           (configuration globale)
├── templates/
│   └── index.html       (gabarit par défaut, obligatoire)
└── parts/
    ├── header.html      (en-tête réutilisable)
    └── footer.html      (pied de page réutilisable)

Le fichier style.css n’a presque plus de rôle stylistique — il sert surtout d’en-tête d’identification. Voici le minimum.

/*
Theme Name: Annuaire Theme
Description: Thème de blocs pour l'annuaire des artisans.
Version: 1.0.0
Requires at least: 6.6
Requires PHP: 7.4
Text Domain: annuaire-theme
*/

Une fois ce dossier en place, le thème apparaît dans Apparence → Thèmes, prêt à être activé. WordPress reconnaît un thème de blocs à la présence du dossier templates/ avec un index.html ; c’est ce qui débloque l’éditeur de site.

✅ Point d’étape — « Annuaire Theme » apparaît dans la liste des thèmes et peut être activé. Après activation, un menu Apparence → Éditeur devient disponible : c’est la signature d’un thème de blocs reconnu.

Étape 2 — Configurer theme.json

Le fichier theme.json est le centre de gravité du thème. On y déclare la version du format (la 3, actuelle depuis WordPress 6.6), puis deux grandes sections : settings, qui définit ce que l’éditeur propose (la palette de couleurs, les tailles de police), et styles, qui applique des valeurs par défaut. Commençons par une palette et une typographie de base.

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {
    "color": {
      "palette": [
        { "slug": "principal", "color": "#1a5e3a", "name": "Vert principal" },
        { "slug": "fond",      "color": "#f7f7f4", "name": "Fond clair" },
        { "slug": "texte",     "color": "#1d1d1b", "name": "Texte" }
      ]
    },
    "typography": {
      "fontSizes": [
        { "slug": "petit",  "size": "0.9rem", "name": "Petit" },
        { "slug": "normal", "size": "1.1rem", "name": "Normal" },
        { "slug": "grand",  "size": "1.6rem", "name": "Grand" }
      ]
    },
    "spacing": {
      "units": [ "px", "rem", "%" ]
    }
  },
  "styles": {
    "color": { "background": "var(--wp--preset--color--fond)", "text": "var(--wp--preset--color--texte)" }
  }
}

Chaque couleur de la palette devient automatiquement une variable CSS — var(--wp--preset--color--principal) — et apparaît dans le sélecteur de couleurs de l’éditeur. C’est la magie du format : déclarez une fois, et la valeur est disponible partout, dans l’interface comme dans les gabarits. Modifier #1a5e3a ici change la couleur principale sur tout le site. Cette centralisation est exactement ce qui manquait aux thèmes classiques, où une couleur était répétée dans des dizaines de fichiers.

Étape 3 — Écrire l’en-tête et le pied de page

Plutôt que de répéter l’en-tête dans chaque gabarit, on le décrit une fois dans parts/header.html sous forme de balisage de blocs, puis on l’inclut partout. Le balisage de blocs ressemble à du HTML commenté : chaque bloc s’ouvre par un commentaire <!-- wp:type -->.

<!-- wp:group {"tagName":"header"} -->
<header class="wp-block-group">
    <!-- wp:site-title /-->
    <!-- wp:navigation /-->
</header>
<!-- /wp:group -->

On reconnaît des blocs natifs : site-title affiche le nom du site, navigation le menu. Le pied de page suit le même principe dans parts/footer.html. Ces parties s’inséreront ensuite dans les gabarits avec un bloc template-part. Découper ainsi évite la duplication : corriger l’en-tête une fois le met à jour sur toutes les pages.

Étape 4 — Le gabarit par défaut

Le gabarit templates/index.html assemble les pièces. Il inclut l’en-tête, affiche le contenu via la boucle de requête (le bloc query), puis le pied de page. C’est l’équivalent déclaratif de l’ancienne boucle PHP.

<!-- wp:template-part {"slug":"header","tagName":"header"} /-->

<!-- wp:query -->
<div class="wp-block-query">
    <!-- wp:post-template -->
        <!-- wp:post-title {"isLink":true} /-->
        <!-- wp:post-excerpt /-->
    <!-- /wp:post-template -->
</div>
<!-- /wp:query -->

<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

Le bloc template-part tire l’en-tête et le pied définis à l’étape précédente. Entre les deux, le bloc query parcourt les contenus et, pour chacun, affiche son titre cliquable et son extrait. Aucune ligne de PHP : WordPress interprète ces blocs et produit le HTML. Activez le thème et visitez l’accueil : la structure s’affiche, alimentée par vos contenus.

Étape 5 — Un gabarit dédié à l’artisan

La hiérarchie des gabarits de WordPress s’applique aussi aux thèmes de blocs. Pour personnaliser l’affichage d’une fiche d’artisan, on crée un fichier au nom conventionnel templates/single-aq_artisan.html. WordPress l’utilisera automatiquement pour toute fiche du type « artisan », sans configuration supplémentaire. On y affiche le titre, le contenu, et nos champs personnalisés.

<!-- wp:template-part {"slug":"header","tagName":"header"} /-->

<!-- wp:group {"tagName":"main"} -->
<main class="wp-block-group">
    <!-- wp:post-title {"level":1} /-->
    <!-- wp:post-featured-image /-->
    <!-- wp:post-content /-->

    <!-- wp:paragraph -->
    <p>Contactez cet artisan par téléphone, ou retrouvez son quartier ci-dessous.</p>
    <!-- /wp:paragraph -->
</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

Les blocs post-title, post-featured-image et post-content affichent respectivement le titre, l’image mise en avant et le contenu de la fiche en cours. Pour afficher les métadonnées aq_telephone et aq_quartier, l’approche moderne consiste à lier un bloc à une métadonnée via les liaisons de blocs (block bindings) ; à défaut, un petit bloc dédié de l’extension peut s’en charger. L’essentiel ici est de comprendre que le nom du fichier — single-aq_artisan.html — suffit à cibler le bon type, par la seule force des conventions.

✅ Point d’étape — Une fiche d’artisan s’affiche avec votre gabarit dédié : titre, image et contenu sont présents, encadrés par votre en-tête et votre pied de page. Si c’est le gabarit générique qui s’applique, vérifiez le nom exact du fichier, clé aq_artisan comprise.

Étape 6 — Éditer depuis l’interface

Le grand avantage du thème de blocs se révèle maintenant. Ouvrez Apparence → Éditeur : vous pouvez modifier l’en-tête, les gabarits, les couleurs, directement à la souris, dans une interface visuelle. WordPress enregistre vos changements en base. Pour les reverser dans le thème et les versionner, l’éditeur propose d’exporter le thème modifié. Ce va-et-vient entre fichiers et interface est nouveau : on prototype visuellement, puis on fige le résultat dans les fichiers du thème. Un client peut même ajuster ses couleurs sans vous appeler, ce qui change la relation de maintenance.

🐞 Pièges fréquents

✅ Récapitulatif

Vous avez construit un thème de blocs avec ses trois fichiers indispensables, configuré couleurs, typographie et espacements dans theme.json version 3, écrit des gabarits en HTML de blocs découpés en parties réutilisables, créé un gabarit dédié au type « artisan » par la seule convention de nommage, et découvert l’édition visuelle depuis l’interface. Annuaire Quartier est désormais complet : des données, un bloc, une API, et un thème pour tout afficher. Vous avez parcouru toute la chaîne du développement WordPress moderne.

🧾 Aide-mémoire

💪 À vous de jouer

Créez un gabarit d’archive templates/archive-aq_artisan.html qui liste tous les artisans avec une boucle de requête limitée au type « artisan ». Indice : le bloc query accepte une configuration de type de contenu.

<!-- wp:query {"query":{"postType":"aq_artisan","perPage":12}} -->
<div class="wp-block-query">
    <!-- wp:post-template -->
        <!-- wp:post-featured-image /-->
        <!-- wp:post-title {"isLink":true} /-->
    <!-- /wp:post-template -->
    <!-- wp:query-pagination -->
        <!-- wp:query-pagination-previous /-->
        <!-- wp:query-pagination-next /-->
    <!-- /wp:query-pagination -->
</div>
<!-- /wp:query -->

Tutoriels de la série

• Créer un bloc Gutenberg en React — un bloc à insérer dans ces gabarits.
• L’API REST WordPress — pour un usage headless de ces mêmes données.

Pour aller plus loin

• 🔝 Retour au guide principal : Développement WordPress : plugins, thèmes et blocs.
• Documentation officielle : Theme Handbook et la référence theme.json.
• Vous avez terminé la série : revenez au guide principal pour relier toutes les briques.

FAQ

Un thème de blocs remplace-t-il définitivement les thèmes classiques ?

Les thèmes classiques restent supportés, mais les thèmes de blocs sont la direction officielle et offrent l’édition visuelle complète. Pour un nouveau projet en 2026, le thème de blocs est le choix par défaut, sauf contrainte technique imposant l’ancien modèle.

Dois-je encore écrire du PHP dans un thème de blocs ?

Pour la structure des pages, non : tout est en HTML de blocs. Un fichier functions.php reste possible pour des réglages (déclarer des tailles d’images, ajouter le support de fonctionnalités), mais il est souvent minimal, voire absent.

Où sont stockées mes modifications faites dans l’éditeur de site ?

En base de données, sous forme de versions qui prennent le pas sur les fichiers du thème. Pour les pérenniser et les versionner avec Git, on exporte le thème depuis l’éditeur, ce qui réécrit les fichiers .html et theme.json.

Comment afficher une métadonnée comme le téléphone dans un gabarit ?

L’approche moderne passe par les liaisons de blocs, qui relient un bloc natif à une métadonnée. À défaut, un bloc dédié fourni par votre extension peut lire la métadonnée et l’afficher. Le gabarit reste alors purement déclaratif.

Le thème et l’extension doivent-ils être livrés ensemble ?

Ce sont deux livrables distincts. L’extension porte la fonctionnalité (le type « artisan »), le thème porte la présentation. On peut changer de thème sans perdre les artisans, et réutiliser l’extension avec un autre thème. Cette séparation est un principe de conception, pas une contrainte technique.