Développer un thème Wordpress compatible avec l'éditeur Gutenberg

De plus en plus de développeurs créent des thèmes WordPress compatibles avec l’éditeur Gutenberg, à l’instar des constructeur de pages historiques (Elementor / Divi etc.).

Gutenberg est l’éditeur par défaut de WordPress, intégré depuis la version 5.0. Il permet aux administrateurs de sites de construire des pages de contenus et des articles en utilisant une interface visuelle basée sur l’ajout de blocs. Gutenberg offre une expérience utilisateur agréable et intuitive, avec de nombreuses possibilités de personnalisation des éléments (Full Site Editing).

Dans ce tutoriel, vous apprendrez comment créer votre propre thème WordPress basé sur des blocs de Gutenberg.

Déclarer un thème WordPress

La première chose à faire pour pouvoir commencer à développer votre thème WordPress est de vous rendre dans le répertoire contenant les thèmes de votre projet /wp-content/themes/. Ajoutez un nouveau répertoire au nom de votre thème.

Le nom du répertoire de votre thème ne doit pas contenir de caractères spéciaux, d’accents ou d’espaces. Si c’est le cas, il ne sera pas reconnu et n’apparaîtra pas dans l’interface d’administration du site.

Un thème WordPress basé sur les blocs de Gutenberg n’a besoin que de deux fichiers de base pour fonctionner :

Le fichier style.css
Le fichier index.html placé dans un dossier /templates.
En option, un fichier screenshot.png correspondant à la miniature du rendu du thème (taille par défaut : 1200px * 900px).

L’arborescence de base de votre thème ressemble donc à cela :

wp-content/themes/montheme/
  - style.css
  - screenshot.png (optionnel)
  templates/
    - index.html

Plutôt simple n’est-ce pas ? Pour que le thème soit fonctionnel et s’affiche dans la rubrique Apparences > Thèmes de l’interface d’administration du site, il va tout de même falloir ajouter quelques lignes de code dans le fichier style.css.

Le fichier style.css

Une fois que vous avez créé l’arborescence de base de votre thème, il est temps d’ouvrir le fichier style.css afin d’y déclarer les informations principales le concernant. Ces informations sont à mettre dans un commentaire, en tout début de fichier. Elles permettent à WordPress de détecter le thème et de l’afficher dans la liste des thèmes de votre site.

/*
Theme Name: Nom du thème
Theme URI: https://www.montheme.fr
Author: Auteur du thème
Author URI: https://www.auteur.fr
Description: La description du thème.
Version: 1.0
Requires at least: 5.0
Tested up to: 6.1
Requires PHP: 7.0
License: GNU General Public License v2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Text Domain: textdomain
*/

Maintenant que votre thème est déclaré correctement, vous pouvez vous rendre dans l’interface d’administration de votre site, à la rubrique Apparences > Thèmes. Vous y verrez apparaître votre thème et vous pourrez l’activer ! Si vous en restez là, vous pourrez commencer à créer des pages et des articles dans l’interface d’administration, mais rien ne s’affichera côté front-office. Voici à quoi va servir le fichier index.html que vous aviez précédemment ajouté dans le dossier /templates de votre thème.

Le template de base : index.html

Comme pour les thèmes utilisant l’éditeur classique de WordPress, les thèmes basés sur les blocs Gutenberg doivent respecter une structure particulière. La principale différence à noter est l’extension des fichiers. La plupart des fichiers d’un thème basé sur les blocs sont en HTML, contrairement aux thèmes classiques utilisant PHP.

Voici un exemple de structure de thème basé sur les blocs Gutenberg :

wp-content/themes/montheme/
  - functions.php
  - editor-style.css
  - style.css
  - screenshot.png (optionnel)
  - theme.json
  assets/ (dossier contenant les fichiers CSS des blocs, les images et les fichiers Javascripts)
  templates/
    - 404.html
    - archive.html
    - index.html
    - page.html
    - single.html
    - search.html
  parts/
    - footer.html
    - header.html

Pour en savoir davantage sur la structure des thèmes basés sur les blocs Gutenberg, vous pouvez consulter cet article de la documentation officielle WordPress.

Le fichier index.html est le template de base de votre thème, utilisé pour afficher les pages et les articles. Ajoutez le code suivant dans votre fichier index.html afin d’afficher le titre et le contenu des publications côté front-office :

<!-- wp:group {"tagName":"main","layout":{"type":"default"}} -->
<main class="wp-block-group">
    <!-- wp:post-title /-->
    <!-- wp:post-content {"layout":{"type":"constrained"}} /-->
</main>
<!-- /wp:group -->

Si vous créez maintenant une page ou un article dans votre interface d’administration et que vous vous rendez son URL, vous y verrez affiché les éléments appelés dans votre template.

Pour connaître tous les types de templates qu’il est possible de créer pour les différents éléments de votre site, consultez cet article du guide officiel des développeurs WordPress.

Gérer les éléments récurrents

Un thème ne se résume généralement pas qu’à un template de base et un fichier de style. Comme vous l’avez vu dans la rubrique précédente, vous pourrez créer des templates spécifiques pour les différents types de contenus de votre site (la page d’accueil, les pages, les articles, les archives etc.). Certains éléments, comme la barre de navigation ou le pied-de-page par exemple, seront présents sur tous les types de contenus que vous allez créer.

Créer des template parts

Pour éviter d’avoir à dupliquer le code de ces parties récurrentes du thème sur chaque template, Gutenberg a mis en place les template parts. Cela consiste à créer des fichiers séparés pour chacun des éléments globaux du site et à les inclure comme des blocs dans les différents templates dans lesquels vous souhaitez les voir apparaître.

Pour ce faire, commencez par ajouter un dossier /parts à la racine de votre thème. À l’intérieur, vous placerez les fichiers HTML correspondant aux parties récurrentes de votre thème, comme la barre de navigation et le pied-de-page.

wp-content/themes/montheme/
  ...
  parts/
    - footer.html
    - header.html

Dans le fichier header.html, ajoutez le code suivant :

<!-- wp:site-logo {"width":150 } /-->
<!-- wp:site-tagline {"textAlign":"center"} /-->

Dans le fichier footer.html, ajoutez le code suivant :

<!-- wp:site-title {"textAlign":"right"} /-->

Maintenant que les fichiers de template parts sont créés et que vous y avez inséré des blocs, voyons comment les appeler dans vos différents templates de contenu.

Inclure les templates parts dans vos templates

Pour inclure les différents template parts dans les templates de votre thème, vous devez utiliser un balisage spécifique.

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

Lorsque vous faites appel à un template part, Gutenberg va automatiquement chercher dans le répertoire /parts du thème le fichier correspondant au slug renseigné dans les paramètres du bloc (les informations dans les accolades). Inutile de préciser l’extension du fichier (.html).

Voici un aperçu du fichier index.html après l’ajout des template parts de la barre de navigation et du pied-de-page :

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

<!-- wp:group {"tagName":"main","layout":{"type":"default"}} -->
<main class="wp-block-group">
    <!-- wp:post-title /-->
    <!-- wp:post-content {"layout":{"type":"constrained"}} /-->
</main>
<!-- /wp:group -->

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

Vous connaissez maintenant les bases du développement d’un thème WordPress compatible avec l’éditeur Gutenberg.

Pour aller plus loin dans le développement de votre thème, vous pouvez lire l’article expliquant comment configurer un thème basé sur les blocs Gutenberg grâce aux fichiers theme.json et functions.php. Vous y apprendrez comment ajouter des traductions à votre thème, déclarer des couleurs, des polices de caractères ou des styles par défaut pour certains blocs. Vous verrez aussi comment limiter certaines options affichées dans l’interface d’administration du site.

Développer un thème WordPress compatible avec l’éditeur Gutenberg