Créer une table des matières à partir des titres en JavaScript

Les pages longues sans navigation frustrent les lecteurs. Ils défilent sans but, perdent leur repère et finissent par partir. Une table des matières dynamique résout ce problème en transformant la structure de vos titres existante en liens d’ancrage cliquables — automatiquement, sans bibliothèque ni framework.

Cet article vous montre comment en construire une en utilisant du JavaScript vanilla moderne, gérer les cas particuliers courants, ajouter une génération de table des matières accessible et, en option, mettre en évidence la section active à mesure que l’utilisateur fait défiler.

Comment fonctionne la navigation par titres dans le DOM

L’idée fondamentale est simple :

1. Interroger tous les éléments de titre du DOM.
2. Générer un id sûr pour chaque titre.
3. Construire une liste de liens d’ancrage pointant vers ces ID.
4. Injecter la liste dans un conteneur désigné.

Pas d’analyse regex de HTML brut. Pas de jQuery. Juste querySelectorAll et les méthodes standards du DOM.

Sélectionner et préparer les titres

const headings = document.querySelectorAll('article h2, article h3, article h4');

Restreignez votre sélecteur à la zone de contenu — article, main ou un conteneur spécifique — afin de ne pas récupérer accidentellement les titres de l’en-tête de votre site ou de la barre latérale.

Générer des ID d’ancrage sûrs

Le texte des titres contient souvent des espaces, caractères spéciaux ou signes de ponctuation qui rendent les fragments d’URL moins lisibles ou peu pratiques à utiliser dans les sélecteurs. Normalisez l’id de chaque titre avant de l’utiliser :

function slugify(text) {
  return text
    .toLowerCase()
    .trim()
    .replace(/\s+/g, '-')
    .replace(/[^\w-]/g, '') || 'section';
}

Gérez les doublons en suivant les slugs utilisés et en ajoutant un compteur :

const usedIds = new Map();

function uniqueSlug(text) {
  const base = slugify(text);
  const count = usedIds.get(base) ?? 0;
  usedIds.set(base, count + 1);
  return count === 0 ? base : `${base}-${count}`;
}

Ignorez les titres vides ou ne contenant que des espaces avec une simple condition de garde : if (!heading.textContent.trim()) return;.

Construire la table des matières en JavaScript

Une fois les ID attribués, construisez la liste de la table des matières et injectez-la dans la page :

function buildTOC(containerSelector, headingSelector) {
  const container = document.querySelector(containerSelector);
  const headings = document.querySelectorAll(headingSelector);
  if (!container || !headings.length) return;

  const nav = document.createElement('nav');
  nav.setAttribute('aria-label', 'Table of contents');

  const ol = document.createElement('ol');

  headings.forEach(heading => {
    const text = heading.textContent.trim();
    if (!text) return;

    const id = heading.id || uniqueSlug(text);
    heading.id = id;

    const li = document.createElement('li');
    const a = document.createElement('a');
    a.href = `#${id}`;
    a.textContent = text;
    li.appendChild(a);
    ol.appendChild(li);
  });

  nav.appendChild(ol);
  container.appendChild(nav);
}

document.addEventListener('DOMContentLoaded', () => {
  buildTOC('#toc', 'article h2, article h3');
});

L’utilisation de DOMContentLoaded garantit que les titres existent avant l’exécution du script.

Génération accessible de la table des matières

Encapsuler la liste dans un élément <nav> avec aria-label="Table of contents" crée un repère de navigation nommé. Les lecteurs d’écran exposent ces repères directement, permettant aux utilisateurs d’accéder à la table des matières sans parcourir la page avec la touche Tab.

Préservez une hiérarchie logique des titres dans votre contenu — ne sautez pas d’un h2 à un h4. La table des matières reflète la structure de votre document : les sauts dans les niveaux de titre produisent une navigation déroutante pour tous les utilisateurs.

Mettre en évidence la section active avec IntersectionObserver

Pour mettre en évidence la section actuellement visible, utilisez l’API IntersectionObserver plutôt que des écouteurs d’événements de défilement :

const observer = new IntersectionObserver(entries => {
  entries.forEach(entry => {
    const id = entry.target.getAttribute('id');
    const link = document.querySelector(`nav a[href="#${id}"]`);
    if (link) link.classList.toggle('active', entry.isIntersecting);
  });
}, { rootMargin: '0px 0px -80% 0px' });

document.querySelectorAll('article h2, article h3').forEach(h => observer.observe(h));

Le rootMargin réduit la zone de détection afin qu’un titre ne soit marqué comme actif que lorsqu’il est proche du haut de la fenêtre d’affichage. Cette approche est plus performante que des gestionnaires de défilement avec throttling et ne nécessite aucun nettoyage pour la plupart des pages statiques. IntersectionObserver est pris en charge par tous les navigateurs modernes.

Défilement fluide

Ajoutez cette unique règle CSS pour activer le comportement de défilement fluide sur l’ensemble de la page, sans aucun JavaScript :

html {
  scroll-behavior: smooth;
}

La propriété scroll-behavior est prise en charge par tous les navigateurs evergreen modernes.

Conclusion

Une table des matières JavaScript fonctionnelle nécessite quatre éléments : une sélection ciblée des titres, une génération d’ID résistante aux collisions, un wrapper sémantique <nav> pour une génération accessible, et un timing basé sur DOMContentLoaded. L’amélioration via IntersectionObserver est facultative, mais apporte une UX significative avec un minimum de code.

Ce schéma fonctionne dans n’importe quel site statique, page de documentation ou blog — sans étape de build, sans dépendances, sans framework requis.

FAQ

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.