# Layout dans theme.json : contentSize, wideSize et blockGap sans mystère

> Comment WordPress génère les largeurs de contenu, les alignements larges et l'espacement vertical, et pourquoi les marges sautent sans prévenir.

- Auteur : Clément Hadrot
- Publié le : 2022-08-19
- Mis à jour le : 2022-08-19
- Catégorie : Thèmes
- URL : https://wpmoderne.dev.wordpress-developpement.fr/themes/layout-theme-json-contentsize-widesize-blockgap/

## L’essentiel

- contentSize définit la colonne de contenu par défaut
- wideSize s'applique aux blocs alignés en largeur
- blockGap centralise l'espacement vertical entre blocs

Sur un thème bloc en cours de finition pour un torréfacteur, les marges entre sections sautaient de façon incohérente selon les pages : parfois serrées, parfois beaucoup trop larges, sans qu'aucune règle CSS écrite à la main n'explique cette variation. La cause, une fois identifiée, venait d'une mauvaise compréhension de trois réglages de `theme.json` : `contentSize`, `wideSize` et `blockGap`, qui pilotent respectivement la largeur de la colonne de contenu, la largeur des blocs alignés en mode large, et l'espacement vertical automatique entre blocs.

Cet article n'aborde pas les presets de couleurs ni la typographie, déjà traités ailleurs : il se concentre uniquement sur le comportement du système de mise en page généré par ces trois réglages.

## contentSize et wideSize : deux largeurs, pas une

Dans la section `settings.layout` de `theme.json`, deux valeurs définissent les largeurs de référence utilisées par tous les blocs qui gèrent l'alignement :

```
{
	"settings": {
		"layout": {
			"contentSize": "720px",
			"wideSize": "1200px"
		}
	}
}
```

`contentSize` correspond à la largeur par défaut d'un bloc, celle utilisée quand aucun alignement particulier n'est choisi. `wideSize` s'applique uniquement aux blocs dont l'option d'alignement « Large » a été sélectionnée dans l'éditeur, une option qui ne devient d'ailleurs disponible que si le thème a préalablement déclaré `"wideSize"`, sans quoi le bouton correspondant reste absent de la barre d'outils du bloc concerné.

## Comment WordPress transforme ces valeurs en CSS

> L'essentiel à retenir : contentSize définit la colonne de contenu par défaut ; wideSize s'applique aux blocs alignés en largeur ; blockGap centralise l'espacement vertical entre blocs

WordPress ne se contente pas de lire ces valeurs : il génère automatiquement les règles CSS correspondantes et les injecte dans la page, à condition que le bloc concerné soit enveloppé dans un groupe avec `"layout": { "type": "constrained" }` ou équivalent au niveau du template. Le CSS généré ressemble, une fois simplifié, à ceci :

```
.is-layout-constrained > * {
	max-width: 720px;
	margin-left: auto;
	margin-right: auto;
}

.is-layout-constrained > .alignwide {
	max-width: 1200px;
}

.is-layout-constrained > .alignfull {
	max-width: none;
}
```

C'est précisément ce comportement automatique qui explique pourquoi ajouter manuellement des règles `max-width` concurrentes dans une feuille de style personnalisée produit des résultats imprévisibles : les deux systèmes de contrainte de largeur entrent en conflit, avec un ordre de priorité qui dépend de la spécificité CSS et de l'ordre de chargement des feuilles de style, difficile à anticiper sans inspecter le résultat final.

## blockGap : l'espacement vertical centralisé

Le réglage `spacing.blockGap` définit l'espace appliqué automatiquement entre deux blocs enfants d'un conteneur qui active la gestion de l'espacement, généralement un bloc Groupe ou Colonnes :

```
{
	"settings": {
		"spacing": {
			"blockGap": true
		}
	},
	"styles": {
		"spacing": {
			"blockGap": "2rem"
		}
	}
}
```

Ce réglage se traduit en variable CSS personnalisée, réutilisée par chaque conteneur qui l'active :

```
.wp-block-group {
	--wp--style--block-gap: 2rem;
}

.wp-block-group.is-layout-flow > * + * {
	margin-block-start: var(--wp--style--block-gap);
}
```

### Le piège identifié sur le projet du torréfacteur

La cause exacte de l'incohérence de marges venait d'un mélange entre des `margin-bottom` écrits manuellement dans une feuille de style additionnelle et le `blockGap` généré automatiquement par certains blocs Groupe. Sur les pages où les deux systèmes coexistaient, les marges s'additionnaient sans qu'aucune règle ne l'explique visuellement à l'œil nu. La correction a consisté à retirer entièrement les `margin-bottom` manuels sur les blocs concernés et à ne piloter l'espacement vertical que par `blockGap`, de façon centralisée dans `theme.json`.

- Ne jamais mélanger marges manuelles et blockGap sur un même conteneur.
- Vérifier, avec l'inspecteur du navigateur, la présence de la variable `--wp--style--block-gap` avant d'ajouter une règle CSS concurrente.
- Documenter, dans le thème, la valeur retenue pour éviter qu'un futur développeur ne réintroduise une marge manuelle par réflexe.

> Un système de mise en page généré automatiquement n'est pas un CSS invisible qu'on peut ignorer : c'est un CSS bien réel, qu'il faut connaître avant d'en ajouter un autre par-dessus.

## Ce qu'il faut retenir

`contentSize`, `wideSize` et `blockGap` ne sont pas de simples préférences esthétiques : ce sont des réglages qui génèrent du CSS bien réel, avec ses propres règles de priorité. Les comprendre évite la plupart des incohérences de marges et de largeurs rencontrées lors des premiers thèmes blocs construits sans cette connaissance préalable.