Table des matières : format et règles

Dans la bibliothèque d’éléments , un aperçu rapide et une table des matières indiquent aux lecteurs ce que couvre une page, ce qu’elle les aidera à décider et comment accéder à la section dont ils ont besoin.

Aperçu rapide. Utilisez cet élément d’ouverture apparié sur les pages longues ou structurellement complexes. Rédigez un aperçu de 40 à 90 mots qui définit le périmètre et le résultat attendu, puis fournissez une liste du sommaire composée des titres H2 stables et uniquement des titres H3 utiles. Sur ce site, le contrôle de contenu en direct ci-dessous reste caché jusqu’à ce que le lecteur ait défilé de plus de 300 pixels ; il apparaît ensuite comme un menu déroulant fixe sous l’en-tête du site.

Pourquoi cet élément est important

Les lecteurs ne commencent pas tous une longue page au même endroit. Une personne a besoin d’une définition, une autre veut des étapes d’implémentation, et une troisième vérifie une seule contrainte avant d’approuver un travail. Un court aperçu répond à la question « Suis-je au bon endroit ? » avant que le lecteur n’investisse son attention. La liste du sommaire répond à la question « Où se trouve la partie dont j’ai besoin ? » sans imposer une lecture linéaire.

Les deux parties sont spécifiées ensemble car elles résolvent des problèmes d’orientation adjacents mais différents. L’aperçu explique la promesse de la page, ses limites et le résultat utile en phrases. La liste du sommaire expose le chemin à travers cette promesse sous forme de destinations. Une liste du sommaire sans aperçu peut montrer qu’une page comporte des sections intitulées « Configuration » et « Accessibilité », mais ne peut expliquer si la page est une introduction conceptuelle ou une spécification de production. Un aperçu sans navigation peut établir le périmètre mais oblige le lecteur à chercher dans 3 000 mots.

Cet élément améliore également l’extractibilité automatique, c’est-à-dire la capacité d’un logiciel à isoler un passage et à conserver son objectif en dehors de la page complète. L’aperçu est un deuxième résumé concis et autonome après le titre et la description. La table des matières source de Hugo est un plan lié et lisible par machine de la couverture et de la hiérarchie de la page ; le rendu collant actuel convertit ces liens en options qui conservent leurs valeurs de fragment d’URL, la partie #section d’une URL. Les systèmes de recherche, les outils de récupération, les extensions de navigateur et les agents d’IA peuvent utiliser le plan du document pour identifier les zones de réponse probables avant de traiter chaque paragraphe. Cela ne garantit pas une fonction de recherche ou une citation par IA ; cela réduit l’ambiguïté sur l’endroit où les sujets commencent et comment ils sont liés.

L’appariement ne doit pas créer de répétition. Un aperçu énonce le périmètre et le résultat. Un bloc de réponse directe répond à la question principale. Les points clés à retenir énoncent les conclusions qui méritent d’être retenues. Quand les trois disent la même chose dans des encadrés différents, l’ouverture devient un obstacle plutôt qu’une aide.

Quand l’utiliser

La liste du sommaire mérite sa place lorsque le saut de section est un comportement probable du lecteur. Le nombre de mots est un indicateur utile, mais la structure est le facteur déterminant.

Utilisez l’aperçu seul lorsque le titre pourrait être interprété largement, lorsque la page exclut délibérément des sujets adjacents, ou lorsque le lecteur a besoin de connaître le résultat attendu avant de continuer. Une page de politique de 900 mots peut nécessiter un aperçu de deux phrases même si elle n’a pas besoin de navigation.

Utilisez la liste du sommaire seule uniquement lorsque le titre et l’ouverture rendent déjà le périmètre indubitable. Cette configuration limite est courante sur les pages de référence : l’ouverture peut contenir une définition directe qui remplit la fonction d’orientation, tandis qu’un long ensemble de champs indépendants nécessite toujours une navigation.

N’utilisez aucune des deux parties comme décoration. Une TOC de six éléments sur un article de 700 mots ajoute une décision supplémentaire avant la réponse. Un aperçu qui dit « Ce guide explore tout ce que vous devez savoir » ne définit ni le périmètre, ni le résultat, ni les exclusions. N’utilisez pas la paire pour masquer une structure de titres faible : si les titres se chevauchent, utilisent une grammaire incohérente ou divisent une idée en de nombreuses petites sections, corrigez d’abord le document avant d’exposer son plan.

Où le placer

La position fait partie du sens de l’élément. L’aperçu doit apparaître après le hero ou la réponse directe d’ouverture et avant le premier H2. Il peut s’agir d’un court paragraphe ou d’une liste compacte, mais il doit être rencontré avant que le lecteur ne s’engage dans le corps du texte. L’invocation de la TOC vient immédiatement après l’aperçu afin que la source rédigée garde l’orientation et la navigation ensemble, même si le contrôle collant de ce site ne devient visible qu’après un défilement de 300 pixels.

La paire ne doit pas interrompre une définition, séparer une affirmation de sa preuve, ni apparaître pour la première fois au milieu du document. Ne la placez pas entre un titre et le paragraphe d’ouverture de ce titre : la relation entre le titre et l’explication doit rester directe. Ne placez pas un autre composant de type aperçu immédiatement à côté. Lorsqu’un bloc de réponse directe ou de points clés à retenir est requis, assignez des rôles distincts et utilisez cet ordre : réponse directe, court aperçu du périmètre, invocation de la TOC, première section du corps. Omettez l’un des résumés si le libellé se chevauche encore.

Utilisez le shortcode une fois par page. Ses IDs rendus (tocDropdown, tocSelect, selectTrigger et les contrôles associés) sont fixes, donc une deuxième instance crée des IDs de document en double et des scripts imprévisibles.

Anatomie

L’élément comporte six régions significatives. Les cinq premières sont du contenu ou du comportement ; l’indicateur de progression est un état. La légende est conservée dans la page afin qu’elle reste lisible lorsque la capture d’écran est redimensionnée ou remplacée.

1. Corps de l’aperçu : 40 à 90 mots indiquant le périmètre, le résultat visé et toute limite importante.
2. Titre du conteneur collant : le titre de la page par défaut, ou l’attribut title rédigé lorsqu’un libellé plus court est plus clair.
3. Étiquette de section courante : commence par « Sélectionnez une section… » et change à mesure que l’IntersectionObserver du navigateur, une API qui détecte les éléments entrant dans une zone d’affichage définie, marque les sections comme actives.
4. Déclencheur du menu déroulant : ouvre la liste générée des destinations de section au clic dans l’implémentation actuelle.
5. Options de titres : liens dérivés de la table des matières de la page Hugo, actuellement H2 et H3 en raison de markup.toml.
6. Barre de progression : montre la proportion du document total défilable parcourue ; elle n’identifie pas l’achèvement des sections.

Exemples de conception

La galerie couvre les états comportementaux plutôt que les thèmes décoratifs. Le contenu sous-jacent reste le même afin que les relecteurs puissent comparer le timing, la hiérarchie, le rognage et l’interaction.

Aucune variante visuelle alternative n’est rédigée via Markdown. title modifie le libellé et class ajoute des classes d’encapsulation, mais aucun ne crée un élément sémantiquement différent. De nouveaux traitements de couleur, carte, barre latérale ou liste en ligne nécessitent une décision de composant plutôt qu’une classe arbitraire ajoutée dans le contenu.

Paramètres

L’aperçu et la TOC partagent un seul contrat éditorial, mais seule la TOC collante est rendue par le shortcode actuel. Les valeurs de configuration sont incluses car elles modifient la sortie même si les auteurs ne peuvent pas les définir par invocation.

La dépendance est facile à manquer : une page sans titre H2 ne rend silencieusement aucune TOC collante car Hugo ne produit aucun plan utilisable et la partie partielle n’émet du balisage que lorsqu’elle a des en-têtes. Avec la configuration actuelle, les H2 et leurs descendants H3 sont éligibles ; les H4 et les titres plus profonds sont exclus. La partie partielle analyse normalement le .TableOfContents de Hugo. Son fallback HTML analyse uniquement les éléments H2 rendus, donc les auteurs ne doivent pas se fier au comportement de fallback pour préserver la navigation H3.

Syntaxe et exemples de code

La notation portable conserve l’aperçu comme corps de l’élément et les paramètres de navigation comme attributs. Les liens des titres restent générés à partir du document environnant plutôt que dupliqués par l’auteur.

:::quick-overview-and-toc{title="Sur cette page" class=""}
Ce guide explique quand utiliser l'élément, comment le contrôle collant Hugo se comporte,
et comment préserver des destinations de section accessibles et stables après la publication.
:::

Le mappage Hugo actuel écrit l’aperçu en Markdown normal et invoque le shortcode fourni une fois. Il n’y a pas de corps JSON.

Ce guide explique quand utiliser l'élément, comment le contrôle collant Hugo se comporte,
et comment préserver des destinations de section accessibles et stables après la publication.

{{< table-of-contents title="Sur cette page" class="" >}}

Le mappage du bloc WordPress stocke le même corps et les mêmes attributs. Un site qui n’a pas enregistré le bloc peut utiliser la forme shortcode équivalente ; il ne doit pas rédiger manuellement les liens des titres.

<!-- wp:amicited/quick-overview-and-toc {"title":"Sur cette page","className":""} -->
<p>Ce guide explique quand utiliser l'élément, comment le contrôle collant se comporte,
et comment préserver des destinations de section accessibles et stables après la publication.</p>
<!-- /wp:amicited/quick-overview-and-toc -->

[amicited_quick_overview_toc title="Sur cette page" class=""]
Ce guide explique le périmètre de l'élément, son comportement et sa politique d'ancres.
[/amicited_quick_overview_toc]

Dans les trois systèmes, la source de vérité est la hiérarchie réelle des titres du document. Une liste maintenue manuellement dérive au fur et à mesure que les titres changent et peut pointer vers des IDs qui ne sont plus présents.

Exemples

Bon exemple

Aperçu rapide. Ce guide montre aux équipes de contenu comment planifier, rédiger, réviser et maintenir une page de comparaison. Il couvre les normes de preuve, les critères de comparaison, les affirmations sur les produits, les tableaux accessibles et les vérifications post-publication. Il ne couvre pas le placement payant ni les conditions de commission d’affiliation.

Sur cette page : Définir la décision · Sélectionner les critères de comparaison · Rassembler les preuves · Rédiger la page · Réviser les affirmations · Mesurer et maintenir

Cela fonctionne car l’aperçu nomme le public, le résultat, la couverture et les limites en 48 mots. Les six destinations sont des tâches distinctes qu’un lecteur pourrait revisiter indépendamment. Leurs libellés utilisent des syntagmes verbaux parallèles, donc les personnes comme les machines peuvent en déduire un processus. Aucune des entrées ne répète le titre de la page ni n’expose une sous-section triviale.

Mauvais exemple

Aperçu : Bienvenue dans notre guide complet. Dans le monde changeant d’aujourd’hui, il y a beaucoup à savoir, alors lisez la suite pour tout apprendre.

Sommaire : Introduction · Plus d’informations · Choses importantes · Autres choses · Conclusion

Cela échoue pour deux raisons. L’aperçu dépense 22 mots sans définir le périmètre, le lecteur, le résultat ou l’exclusion. Les entrées étiquettent des contenants rhétoriques plutôt que des sujets, donc elles n’aident pas un lecteur à prédire où se trouve une réponse. Ajouter plus de titres ne résoudrait pas le problème ; le document a d’abord besoin de limites de sections significatives.

Un second cas limite est une réponse de 600 mots avec « Aperçu », « Contexte », « Détails », « Conseils » et « Conclusion » dans sa TOC. Même si chaque ancre fonctionne, la liste ajoute plus d’interface que de valeur de navigation. Gardez l’ouverture directe et supprimez la TOC.

Balisage schema et accessibilité

Ici, le balisage schema désigne un code standardisé lisible par machine qui identifie les entités et les propriétés. Cet élément n’a pas de type ou de propriété dédié dans le vocabulaire Schema.org, et le shortcode Hugo n’émet pas de JSON-LD, la notation basée sur des scripts couramment utilisée pour publier ce vocabulaire. Ne marquez pas la TOC comme ItemList simplement parce qu’il s’agit d’une liste ; cela suggérerait une liste d’éléments de sujet plutôt qu’une navigation. L’aperçu peut informer la description d’une page uniquement lorsque le libellé est indépendamment approprié, mais il n’est pas copié automatiquement dans les données structurées.

Le comportement HTML et ARIA importe davantage ici. ARIA, la norme Accessible Rich Internet Applications, fournit des rôles, des noms et des états lorsque le HTML natif ne le fait pas. Un point de repère (landmark) est une région nommée de la page vers laquelle les utilisateurs de technologies d’assistance peuvent sauter. Le focus est la cible courante d’interaction au clavier.

Ce sont des faits d’implémentation, pas une permission d’ignorer l’accessibilité. Les relecteurs de contenu peuvent vérifier la clarté des titres, les IDs uniques et l’ordre logique dès aujourd’hui. Les propriétaires de composants doivent résoudre le comportement du déclencheur, du point de repère, du focus, de l’URL et du mouvement réduit avant de décrire la variante collante comme accessible au clavier.

Règles de rédaction

Rédigez l’aperçu après que la structure de la page est stable. Cela empêche une promesse précoce de s’éloigner de la couverture finale. Gardez-le entre 40 et 90 mots. Préférez deux ou trois phrases ; utilisez trois à cinq puces uniquement lorsque la page contient plusieurs résultats véritablement parallèles. Indiquez ce que la page aide le lecteur à comprendre, décider ou faire. Nommez une exclusion lorsque le titre pourrait raisonnablement promettre plus que ce que la page livre.

Utilisez H2 pour les questions, étapes ou domaines de décision majeurs de la page. Incluez H3 dans la navigation uniquement lorsqu’il s’agit d’une destination indépendante utile sous un H2 substantiel. Sur ce site, la configuration inclut automatiquement chaque H2 et H3, donc la politique pratique est plus stricte : ne créez pas de titre à moins qu’il ne mérite d’apparaître dans la navigation. Visez 5 à 18 entrées au total. Si la liste générée dépasse 18 entrées, combinez les sections qui se chevauchent, supprimez les titres H3 inutiles ou divisez la page. Ne sautez jamais directement de H2 à H4 pour cacher un titre de la TOC ; les niveaux de titres expriment la hiérarchie, pas le style ou la préférence de navigation.

Utilisez un texte de titre concis et descriptif. Un lecteur devrait comprendre chaque destination sans lire son paragraphe parent. Préférez les formes parallèles dans une séquence : « Choisir les critères », « Rassembler les preuves » et « Réviser les affirmations » sont plus faciles à parcourir qu’un mélange de noms, de questions et d’étiquettes vagues. Ne mettez pas de citations, d’affirmations promotionnelles, d’émojis, de badges de statut ou de phrases complètes dans un titre uniquement pour influencer la TOC.

L’aperçu ne doit jamais contenir une seconde liste de sommaire miniature, des affirmations de performance non étayées ou des instructions qui n’apparaissent nulle part dans le corps. La TOC ne doit jamais contenir d’ancres tapées manuellement, de destinations en dehors de la page courante ou de liens vers des sections vides.

Politique de stabilité des ancres

Un ID de titre est la partie fragment d’une URL, comme #anchor-stability-policy. Les fragments d’URL publiés sont des interfaces publiques. Les signets, les liens de campagne, la documentation de support, les résultats de recherche et les réponses générées par IA peuvent pointer directement vers eux. Modifier le texte du titre peut changer l’ID généré par Hugo et briser chaque ancre entrante même si l’URL de la page reste la même.

Après publication, figez les IDs de tous les titres H2 et H3. Préférez modifier le paragraphe sous un titre plutôt que de renommer le titre. Lorsqu’un renommage est nécessaire, préservez l’ancien ID via un mécanisme d’ancre explicite pris en charge par le système de publication, puis vérifiez à la fois l’ancien fragment entrant et la nouvelle sélection de la TOC. Ne réutilisez jamais un ancien ID pour un sujet différent, ne dupliquez jamais un ID sur la page, et ne traduisez jamais un ID sur une URL localisée existante sans plan de migration. Enregistrez les modifications intentionnelles d’ancres dans la note de version ou le journal des modifications de contenu afin que les propriétaires de liens entrants connus puissent les mettre à jour.

Types d’articles qui l’utilisent

Le champ postTypes du frontmatter liste les formats pour lesquels cet élément fait partie du schéma de production. Il reste conditionnel : une instance courte d’un format normalement long peut tomber en dessous du seuil de la TOC.

Les pages de produit, de catégorie et de cas d’usage ne sont pas incluses par défaut car leurs parcours principaux sont souvent gérés par la navigation au niveau de la page et les appels à l’action. N’ajoutez cet élément que par le biais d’une décision documentée de template, pas parce que la page se trouve être longue.

Liste de contrôle QA

• Confirmez que la page atteint le seuil : au moins 1 800 mots, sept sections H2, ou un besoin documenté de navigation non linéaire.
• Confirmez que l’aperçu fait 40 à 90 mots et énonce le périmètre, le résultat visé et toute exclusion nécessaire.
• Confirmez que l’aperçu ne répète pas la réponse directe ni les points clés à retenir.
• Confirmez que le shortcode apparaît une fois, immédiatement après l’aperçu et avant le premier H2.
• Confirmez que chaque H2 est une destination majeure significative et que chaque H3 est suffisamment utile pour apparaître dans la navigation.
• Confirmez que la liste générée contient 5 à 18 entrées, utilise un ordre logique et ne contient aucun élément H4 avec la configuration actuelle.
• Confirmez que config/_default/markup.toml utilise toujours startLevel = 2, endLevel = 3 et ordered = false, ou mettez à jour cette spécification avec le changement de composant.
• Confirmez qu’une page sans H2 éligible ne prétend pas contenir une TOC ; le shortcode ne rendra silencieusement rien.
• Confirmez que chaque fragment généré est unique et atteint le titre visé.
• Testez les URL d’ancres entrantes publiées avant de modifier tout libellé de H2 ou H3 ; préservez les anciens IDs lorsque les titres doivent changer.
• Sur bureau, vérifiez que l’encapsuleur collant est caché à 300 pixels ou moins et apparaît après que la position de défilement dépasse 300 pixels.
• Vérifiez que l’encapsuleur fixe se trouve sous l’en-tête réel, que la barre de progression avance et que l’étiquette active suit les changements de section.
• Vérifiez que les fenêtres étroites n’affichent pas le contrôle actuel, et enregistrez cela comme un comportement actuel attendu plutôt qu’une capture d’écran cassée.
• Enregistrez les limitations d’accessibilité actuelles : pas de point de repère de navigation, pas de déclencheur visible focalisable au clavier, pas de transfert de focus, pas de mise à jour de fragment et pas de branche de mouvement réduit.
• Confirmez qu’aucun chemin de capture d’écran n’est rendu tant que l’actif correspondant n’existe pas sur le disque.

FAQ

Les questions ci-dessous couvrent les décisions éditoriales qui font que cet élément est le plus souvent ajouté trop tôt, rendu trop profond ou cassé après la publication.