Comprendre la structure d’un thème WordPress pour Gutenberg

Pour créer ou éditer un thème WordPress, il est important d’en comprendre la logique : comment les différents fichiers du thème s’articulent entre eux, quelle est leur fonction, comment tout cela devrait être organisé ? Faisons un tour rapide de l’arborescence des fichiers d’un thème WordPress récent compatible avec Gutenberg pour mieux comprendre la structure d’un thème WordPress, puis attardons nous sur quelques fichiers clés.

Comprendre
l’arborescence d’un thème WordPress

Dans sa version 6.8, un thème WordPress pour Gutenberg contient généralement les fichiers suivants :

mon-theme/
|
└── assets/                   # Dossier ressources CSS, JS, images...
│   └── css/
│        └── editor-style.css                             
│   └── images/
│   └── fonts/
│               
└── styles/                   # Dossier des styles JSON
│   └── blocks/
│   └── colors/
│   └── sections/
│   └── typography/
│ 
└── templates/                # Dossier modèles HTML     
│   └── 404.html               
│   └── archive.html               
│   └── home.html
│   └── index.html
│   └── page.html
│   └── search.html
│   └── single.html
│
└── parts/                     # Dossier éléments de modèles HTML
│   └── header.html            
│   └── footer.html            
│
└── patterns/                  # Dossier des compositions PHP
│
└── functions.php              # fonctions du thème                    
└── screenshot.png             # Capture d'écran
└── style.css                  # Feuille de style principale
└── theme.json                 # Paramètres du site 

On peut faire quelques remarques à propos de cette arborescence…

Les feuilles de style
style.css et editor-style.css

• La feuille de style principale style.css doit contenir les informations qui permettent de lister le thème dans l’administration. De façon surprenante, elle n’est pas liée par défaut à la partie publique du site.
• Les styles écrits dans un fichier .CSS et chargés sur le site public devront être copiés dans editor-style.css pour qu’ils soient visibles à l’édition d’un article ou d’une page. Ce fichier .CSS n’est pas non plus chargé par défaut.

Vous l’aurez compris, si en éditant le fichier style.css d’un thème vos modifications n’apparaissent pas, c’est sans doute parce que la feuille de style n’est pas liée à la partie visible du site. Pour régler le problème, on référence les deux feuilles de style en éditant le fichier function.php de cette façon :

// lien vers editor-style.css dans l'éditeur visuel.
if ( ! function_exists( 'monTheme_editor_style' ) ) :
	function monTheme_editor_style() {
		add_editor_style( 'assets/css/editor-style.css' );
	}
endif;
add_action( 'after_setup_theme', 'monTheme_editor_style' );

// lien vers style.css sur le site public.
if ( ! function_exists( 'monTheme_enqueue_styles' ) ) :
	function monTheme_enqueue_styles() {
		wp_enqueue_style(
			'monTheme-style',
			get_parent_theme_file_uri( 'style.css' ),
			array(),
			wp_get_theme()->get( 'Version' )
		);
	}
endif;

C’est ainsi que procède le thème 2025 par défaut de WordPress. Il est néanmoins possible de faire différemment et enregistrer les styles CSS supplémentaires en base de donnée avec l’éditeur Gutenberg, mais à l’usage c’est une option peu pratique.

JavaScript et images…
Les autres ressources

• Le javascript : il est possible d’ajouter un lien vers un fichier script.js personnalisé – par exemple dans le footer – en ajoutant à function.php la fonction nécessaire. :

if ( ! function_exists( 'monTheme_enqueue_script' ) ) :
function monTheme_enqueue_script() {
wp_enqueue_script(
'monTheme-script',
get_template_directory_uri() . '/assets/script.js',
[], // dépendances
null, // version
true // charger dans le footer
);
}
endif;
add_action( 'wp_enqueue_scripts', 'monTheme_enqueue_script' );

• Les images placées dans le fichier assets/ sont dédiées au thème et seront utilisées par exemple dans les feuilles de styles ou dans les compositions : elles n’apparaîtront pas dans le gestionnaire de média et ont généralement vocation à être remplacées.
• Les polices de caractères, optionnelles, seront placées dans le dossier fonts/ et pourront être sélectionnées dans l’éditeur. A l’usage, le chargement des polices arrive tard. On peut aussi les charger plus tôt dans l’interface en ajoutant une fonction au fichier function.php (ci-dessous la police Manrope). On peut ainsi profiter du CDN de Google pour charger la police de caractères…

if ( ! function_exists( 'monTheme_enqueue_google_fonts') ) :

function monTheme_enqueue_google_fonts() {
    // Préchargement
    echo '<link rel="preconnect" href="https://fonts.googleapis.com">' . "\n";
    echo '<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>' . "\n";
    echo '<link href="https://fonts.googleapis.com/css2?family=Manrope:wght@200..800&display=swap" rel="stylesheet">' . "\n";
}
endif;

add_action( 'wp_head', 'monTheme_enqueue_google_fonts', 1 );

Compositions et modèles

• Le dossier patterns/ inclue les compositions sélectionnables dans l’éditeur Gutenberg. Elles sont au format PHP, mais on y trouve majoritairement du HTML, dont des commentaires spécifiques à Gutenberg – les mêmes qui sont utilisés dans les modèles au format HTML.

• Les dossiers templates/ et parts/ constituent l’ossature du thème WordPress. Ce sont respectivement les modèles et les éléments de modèles que l’on retrouve dans l’administration du site – plus précisément dans l’éditeur de thème – et sont modifiables à souhait.
• Il est intéressant de constater que, dans le thème Twentytwentyfive, ces fichiers HTML font largement appel aux compositions situées dans le dossier pattern . Exemple, ci-dessous, avec l’élément de modèle header qui, en réalité, ne fait qu’inclure le contenu de patterns/header.php.

<!-- wp:pattern {"slug":"twentytwentyfive/header"} /-->

Ces compositions sont donc au cœur du thème par défaut, et on en comprend donc la logique générale : si les modèles structurent le site, les compositions, d’une grande souplesse et extrêmement variées, permettent de « composer » les modèles très facilement. Voyez ci-dessous la démonstration de l’édition du modèle de Blog dans le thème 2025 :

L’utilisation de ces compositions est aussi facilitée par le nouveau répertoire des compositions (en anglais patterns) : https://wordpress.org/patterns/

On peut créer de nouvelles compositions en utilisant l’éditeur visuel, et les compositions peuvent être synchronisées : il est possible de modifier les différentes occurrences d’une même composition.

Les fichiers JSON
Le Thème et les styles (encore)

Les fichiers au format JSON sont largement utilisés par WordPress pour paramétrer le thème et définir les styles généraux du thème ainsi que des déclinaisons de style pour tout le site ou par bloc.

• Le fichier principal du thème n’est donc plus la feuille de style.css à la racine mais bien le fichier theme.json.
• Le dossier styles/ vient compléter le fichier theme.json en ajoutant des variations de styles qui peuvent remplacer les styles généraux quand ils sont sélectionnés. On retrouve ces variations à plusieurs endroits :
  • Dans l’éditeur de style, en cliquant sur Parcourir les styles (image 1). Au clic sur le bouton, on a accès aux variations de couleurs et de polices de caractères pour tout le site.
  • A l’édition d’articles ou de page, en sélectionnant un bloc dont une variation a été définie. Dans le thème 2025, c’est le cas par exemple des blocs paragraphe, image ou encore liste ( image 2)

Les fichiers JSON servent donc à définir des styles précis qui, sélectionnés par l’utilisateur, seront appliqués au site ou au bloc.

Pour conclure…

C’est une façon de procéder radicalement différente de l’édition de thème classique que nous propose l’équipe de développement de WordPress. Les fichiers JSON sont les plus importants pour définir les styles du site, mais ils ont un schéma propre à WordPress, et, si la syntaxe n’est pas impossibles à appréhender, elle n’est pas non plus très intuitive comparée aux CSS. Un éditeur avancé (VS code) facilite le travail sur les fichiers JSON du thème, avec des commentaires et l’auto-complétion.

Générer le fichier theme.json à l’aide d’utilitaires comme l’extension create block theme ou d’autres applications web est possible. Une recherche portant sur les mots clés « wordpress json theme generator » vous renverra plusieurs résultats. Ces générateurs permettent de sélectionner des valeurs pour chaque option du theme.json. C’est utile si on sait déjà à quoi correspond chacune de ces options… mais si on le sait déjà, est-ce qu’un générateur est vraiment utile ?

Il apparait évident que la bonne compréhension de la structure des fichiers JSON de WordPress et leur édition sera nécessaire pour penser, organiser et créer un thème pour Gutenberg. Donner à l’utilisateur final la possibilité d’éditer le site facilement en sélectionnant des compositions déjà prêtes ou en choisissant des blocs aux styles variés et néanmoins prédéfinis est donc la voie tracée par l’équipe de WordPress aux développeurs de thème. Ce n’est pas la voie la plus simple… mais c’est celle à suivre pour bénéficier d’un éditeur visuel avancé et agréable à l’utilisation.