# Un bloc de liste d’articles qui casse la hiérarchie des titres selon le contexte

> Le même bloc « articles liés » place tantôt un h2, tantôt un h4 selon la page où il s'affiche, sans qu'aucun titre n'ait été modifié à la main. Le niveau doit devenir paramétrable.

- Auteur : WordPress Développement
- Publié le : 2022-10-15
- Mis à jour le : 2022-10-15
- Catégorie : Accessibilité
- URL : https://www.wpmoderne.fr/accessibilite/hierarchie-titres-dynamique-heading-levels/

## L’essentiel

- Un même bloc réutilisé peut produire des niveaux de titre incohérents selon le contexte
- Le niveau de titre doit être un paramètre du bloc, pas une valeur codée en dur
- Un contrôle automatisé par page ne détecte pas ce type d'incohérence inter-pages

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'essentiel à retenir : Un même bloc réutilisé peut produire des niveaux de titre incohérents selon le contexte ; Le niveau de titre doit être un paramètre du bloc, pas une valeur codée en dur ; Un contrôle automatisé par page ne détecte pas ce type d'incohérence inter-pages

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.