Démarrer un nouveau thème bloc sans arborescence pensée à l’avance, c’est prendre le risque de se retrouver, trois semaines plus tard, avec un dossier templates contenant vingt fichiers aux noms approximatifs et un dossier parts où personne ne sait plus quelle template part sert encore. J’ai vécu cette situation sur un premier projet FSE, et j’ai depuis posé une structure que je réutilise systématiquement en démarrage de chantier.
Voici l’arborescence complète que j’utilise pour un projet de taille moyenne, environ douze gabarits, avec la logique de nommage qui va derrière chaque dossier.
La structure de dossiers complète
Un thème bloc respecte une structure minimale imposée par WordPress (les dossiers templates et parts à la racine, avec theme.json et style.css), mais tout le reste de l’organisation reste à la discrétion du développeur. Voici la structure que je pose systématiquement avant le premier commit :
theme-client/
├── style.css
├── theme.json
├── functions.php
├── templates/
│ ├── index.html
│ ├── front-page.html
│ ├── home.html
│ ├── single.html
│ ├── page.html
│ ├── page-contact.html
│ ├── archive.html
│ ├── archive-projet.html
│ ├── single-projet.html
│ ├── search.html
│ ├── 404.html
│ └── singular.html
├── parts/
│ ├── header.html
│ ├── header-transparent.html
│ ├── footer.html
│ ├── sidebar-projet.html
│ └── cta-newsletter.html
├── patterns/
│ ├── hero-accueil.php
│ ├── grille-services.php
│ ├── temoignages.php
│ └── footer-liens-legaux.php
└── assets/
├── fonts/
└── icons/La logique derrière le dossier templates
Le dossier templates reçoit exclusivement des fichiers correspondant à un usage validé par la hiérarchie native de WordPress : jamais de fichier utilitaire ou de brouillon qui traînerait là « en attendant ». Le nommage suit strictement les conventions du Core : archive-{cpt}.html, single-{cpt}.html, page-{slug}.html pour les pages qui nécessitent un gabarit dédié réellement identifié par leur slug plutôt que par un nom générique.
Sur ce projet de douze gabarits, la répartition typique est : trois templates génériques (index, page, single), deux templates spécifiques à des pages précises (page-contact, front-page), deux templates liés au CPT « Projet » (archive-projet, single-projet), et le reste couvrant les cas obligatoires (404, search, archive, home, singular en filet de sécurité).
Le dossier parts : nommer par fonction, pas par apparence
La règle la plus utile que j’applique sur le dossier parts : nommer chaque fichier par sa fonction et non par son apparence visuelle du moment. Un fichier nommé header-fond-bleu.html devient un mensonge dès que le graphiste change la couleur ; header-transparent.html, en revanche, reste vrai tant que le comportement (transparence sur le hero) ne change pas, même si la teinte évolue.
header.html: header standard utilisé sur la majorité des pages.header-transparent.html: variante utilisée uniquement sur les templates avec un hero en pleine largeur.sidebar-projet.html: élément latéral spécifique au CPT Projet, jamais réutilisé ailleurs.
Pourquoi les patterns vivent dans un dossier séparé, en PHP
Contrairement aux templates et parts, enregistrés en HTML pur, mes patterns sont déclarés en PHP via register_block_pattern(), avec le contenu de bloc stocké dans une chaîne de caractères ou un fichier séparé. Ce choix permet d’insérer des valeurs dynamiques (année en cours pour un copyright, nombre d’articles publiés) directement dans un pattern, ce qu’un fichier HTML statique ne permettrait pas.
<?php
register_block_pattern(
'theme-client/footer-liens-legaux',
array(
'title' => __( 'Liens légaux du pied de page', 'theme-client' ),
'categories' => array( 'theme-client' ),
'content' => sprintf(
'<!-- wp:paragraph --><p>© %d — Tous droits réservés</p><!-- /wp:paragraph -->',
gmdate( 'Y' )
),
)
);Ce qu’on évite absolument
Trois pièges reviennent systématiquement sur les projets que je reprends d’une autre équipe : des templates qui dupliquent une template part au lieu de l’appeler, un dossier parts qui grossit sans qu’aucun fichier ne soit jamais supprimé (des parts orphelines datant d’une V1 abandonnée), et un mélange de fichiers .html et .php dans le même dossier sans raison technique claire.
Une arborescence de thème bloc doit rester compréhensible par quelqu’un qui n’a jamais vu le projet, rien qu’en lisant les noms de fichiers. Si un nom nécessite une explication orale, il est probablement mal choisi.
Pour aller plus loin
Cette structure n’est pas figée : sur un projet à cinquante gabarits, elle demande une subdivision supplémentaire par type de contenu. Mais pour un site vitrine ou institutionnel de taille moyenne, ces douze gabarits organisés selon cette logique couvrent la quasi-totalité des besoins, sans qu’un nouveau développeur rejoignant l’équipe ait besoin de plus de dix minutes pour s’orienter dans le projet.
