# Arborescence d’un thème bloc à douze gabarits : notre organisation type

> Avant le premier commit d'un nouveau projet FSE de taille moyenne, voici la structure de dossiers, le nommage des templates et des template parts que nous suivons.

- Auteur : Clément Hadrot
- Publié le : 2024-06-27
- Mis à jour le : 2024-06-27
- Catégorie : FSE
- URL : https://wpmoderne.dev.wordpress-developpement.fr/fse/arborescence-theme-bloc-douze-gabarits/

## L’essentiel

- Un dossier par nature de fichier, jamais de mélange templates et parts
- Un préfixe de nommage pour les parts réutilisées à plusieurs endroits
- Douze gabarits restent lisibles si la nomenclature est posée dès le départ

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

> L'essentiel à retenir : Un dossier par nature de fichier, jamais de mélange templates et parts ; Un préfixe de nommage pour les parts réutilisées à plusieurs endroits ; Douze gabarits restent lisibles si la nomenclature est posée dès le départ

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.