Pourquoi le même bloc « Articles liés » affiche-t-il un h2 sur la page d’accueil, un h3 sur une page catégorie et un h4 sur une fiche article, sans qu’aucun contenu n’ait été retouché manuellement ? Cette question est remontée d’un audit d’accessibilité qui signalait, sur certaines pages seulement, l’alerte « Heading levels should only increase by one » sans réussir à en expliquer la cause au premier regard.
Le bloc en question était un bloc Gutenberg personnalisé développé en interne, conçu pour être inséré n’importe où dans le contenu, avec un niveau de titre codé en dur dans son rendu PHP. Le résultat dépendait entièrement de l’endroit où le bloc était inséré, ce qui produisait des hiérarchies de titres différentes d’une page à l’autre pour un composant pourtant strictement identique.
Symptôme : une incohérence qui varie selon la page
Sur la page d’accueil, le bloc suivait directement le titre principal h1 puis un premier h2 de section, et son propre titre en h2 restait cohérent. Sur une fiche article, en revanche, la structure du gabarit plaçait déjà un h1 (titre de l’article), un h2 (nom de l’auteur ou section « À propos »), un h3 (sous-titre d’une section du contenu), et le bloc « Articles liés » inséré en bas de page continuait d’afficher un h2 fixe, créant un saut de niveau incohérent en remontant après un h3.
Cette incohérence n’apparaissait pas sur un audit rapide d’une seule page, car chaque page prise isolément pouvait sembler correcte ou presque. C’est la comparaison systématique de plusieurs gabarits contenant le même bloc qui a révélé le problème structurel sous-jacent.
Diagnostic : un niveau codé en dur dans le rendu du bloc
L’inspection du fichier de rendu du bloc a confirmé l’hypothèse : la fonction de rendu PHP générait systématiquement un élément <h2> pour le titre de la section « Articles liés », sans tenir compte du contexte d’affichage ni proposer de réglage à l’utilisateur final dans l’éditeur.
function render_bloc_articles_lies( $attributes, $content ) {
$titre = '<h2 class="articles-lies-titre">Articles liés</h2>';
return $titre . render_liste_articles( $attributes );
}Ce code fonctionnait correctement dans le contexte pour lequel il avait été pensé à l’origine (la page d’accueil), mais aucune vérification n’avait été faite lors de sa réutilisation ultérieure sur d’autres gabarits, où la hiérarchie de titres environnante différait.
Correctif : rendre le niveau de titre paramétrable
La solution retenue a consisté à transformer le niveau de titre en attribut réglable du bloc, avec une valeur par défaut raisonnable mais modifiable depuis l’éditeur. L’API Gutenberg des blocs prévoit précisément ce cas de figure via un attribut de type entier, couplé à un composant HeadingLevelDropdown dans l’interface de réglage du bloc.
registerBlockType( 'theme/articles-lies', {
attributes: {
niveauTitre: {
type: 'number',
default: 2
}
}
} );
function render_bloc_articles_lies( $attributes, $content ) {
$niveau = isset( $attributes['niveauTitre'] ) ? (int) $attributes['niveauTitre'] : 2;
$titre = sprintf(
'<h%1$d class="articles-lies-titre">Articles liés</h%1$d>',
$niveau
);
return $titre . render_liste_articles( $attributes );
}Une fois ce changement livré, chaque gabarit a pu recevoir un niveau de titre adapté à son propre contexte hiérarchique : h2 sur la page d’accueil, h4 sur la fiche article où la structure locale l’imposait. L’intégrateur qui place le bloc devient responsable du bon niveau, ce qui est la bonne répartition des responsabilités puisque lui seul connaît la hiérarchie complète du gabarit à cet endroit précis.
Prévention : documenter la hiérarchie attendue par gabarit
Pour éviter que ce type d’incohérence ne revienne avec un futur bloc réutilisable, une documentation courte a été ajoutée au guide de style interne du thème, précisant la structure de titres attendue pour chaque gabarit principal (accueil, catégorie, article, page). Tout nouveau bloc pensé pour être inséré à plusieurs endroits doit désormais exposer son niveau de titre comme réglage, jamais comme valeur codée en dur.
- Documenter la hiérarchie de titres attendue par gabarit
- Rendre systématiquement paramétrable le niveau de titre d’un bloc réutilisable
- Tester chaque bloc sur au moins deux gabarits différents avant mise en production
- Ne jamais valider un audit d’accessibilité sur une seule page isolée pour un bloc partagé
En résumé
Un bloc réutilisable qui code en dur son niveau de titre finit toujours par produire des incohérences de hiérarchie sur au moins un des gabarits où il est inséré. Rendre ce niveau paramétrable, avec une valeur par défaut sensée, transfère la bonne décision à la personne qui connaît réellement le contexte d’insertion, et évite ce type de régression difficile à détecter sur un audit page par page.
