Générateur de table des matières Markdown : navigation automatique pour vos docs

Tout développeur a vécu cette situation : en plein milieu de la rédaction d'un long README, on réalise qu'une table des matières serait utile. On passe alors vingt minutes à la créer manuellement — convertir chaque titre en minuscules, remplacer les espaces par des tirets, supprimer les caractères spéciaux, construire les liens un par un. Puis un titre change, la moitié des liens se cassent. Un nouveau chapitre est ajouté, la table des matières est déjà obsolète.

C'est un problème mineur mais réellement agaçant, qui a pourtant une solution entièrement mécanique. L'algorithme de génération des identifiants d'ancre pour GitHub-Flavored Markdown est déterministe et bien documenté. Il n'y a aucune raison de le faire à la main.

Le Générateur de table des matières Markdown automatise l'ensemble du processus. Collez votre Markdown, obtenez une table des matières correctement indentée avec les bons liens, prête à être intégrée directement dans votre document.

Pourquoi les tables des matières comptent vraiment

Une table des matières n'est pas décorative. Dans un document long, elle remplit une vraie fonction de navigation : les lecteurs la parcourent d'abord pour comprendre ce que couvre le document, puis sautent directement à la section qui les intéresse. Sans elle, ils font défiler la page manuellement ou abandonnent.

Pour les fichiers README sur GitHub, c'est particulièrement vrai. Quand un développeur atterrit pour la première fois sur un dépôt, il parcourt le README. Si celui-ci est long et ne comporte pas de table des matières, construire une image mentale du projet prend plus de temps. Une table des matières claire communique instantanément la structure du projet.

La documentation technique suit la même logique. Les références API, les guides d'architecture, les docs d'onboarding — les lecteurs ne les lisent presque jamais de façon linéaire. Ils cherchent quelque chose de précis. La table des matières est leur plan.

Comment fonctionne l'algorithme d'ancre

GitHub génère les identifiants d'ancre à partir du texte des titres selon un processus simple :

1. Supprimer toutes les balises HTML
2. Mettre l'ensemble du texte en minuscules
3. Supprimer toute la ponctuation sauf les tirets et les espaces
4. Remplacer les espaces par des tirets
5. Déduplication : si un titre apparaît plusieurs fois, ajouter -1, -2, etc.

Ainsi, ## Référence API (v2) devient #référence-api-v2. ## Premiers pas devient #premiers-pas.

Le français avec ses caractères accentués se comporte bien ici. GitHub conserve les caractères Unicode dans les ancres. Un titre comme ## Foire aux questions devient #foire-aux-questions. Cela fonctionne correctement dans les navigateurs modernes, même si l'URL peut sembler étrange avec l'encodage en pourcentage.

La différence entre GitHub et GitLab

GitHub et GitLab suivent le même algorithme de base mais divergent légèrement sur certains caractères. Pour la plupart des documentations françaises ordinaires, les résultats sont identiques. Les différences apparaissent avec :

• Certains signes de ponctuation comme les parenthèses : supprimés par GitHub, traités différemment par GitLab dans certains cas
• Les emoji dans les titres : le comportement est incohérent sur les deux plateformes

Le conseil pratique si vous publiez sur les deux plateformes : gardez les textes de titres simples — des mots ordinaires, peu de ponctuation.

Exemple concret

Voici une structure de README typique :

# Ma bibliothèque

## Installation

### macOS

### Linux

## Démarrage rapide

## Référence API

### Options de configuration

### Méthodes

## Contribuer

## Licence

Le générateur produit :

## Table des matières

- [Installation](#installation)
  - [macOS](#macos)
  - [Linux](#linux)
- [Démarrage rapide](#démarrage-rapide)
- [Référence API](#référence-api)
  - [Options de configuration](#options-de-configuration)
  - [Méthodes](#méthodes)
- [Contribuer](#contribuer)
- [Licence](#licence)

Notez quelques points : # Ma bibliothèque en H1 est exclu de la table des matières — H1 est le titre du document, pas une cible de navigation. La hiérarchie est correctement reflétée — H2 au niveau supérieur, H3 avec une indentation.

Cas particuliers et limitations honnêtes

Il vaut mieux être direct sur certains aspects.

Emoji dans les titres — Populaires dans les fichiers README : ## 🚀 Premiers pas. Le comportement des ancres varie selon le renderer. Si vos titres contiennent des emoji, vérifiez les liens générés directement sur la plateforme cible.

Spans de code dans les titres — ## La fonction `render()` — les backticks sont supprimés, ce qui donne #la-fonction-render. C'est généralement le résultat voulu.

Parenthèses et caractères spéciaux — ## Référence API (v2) — les parenthèses sont supprimées, donnant #référence-api-v2. Ça fonctionne bien, mais si vous avez plusieurs sections aux noms similaires, l'ancre peut prendre une forme inattendue.

Intégration dans votre flux de travail

Le flux de travail typique est simple :

1. Rédigez d'abord votre document, sans vous soucier de la table des matières
2. Quand la structure est stabilisée, collez le Markdown dans le Générateur de table des matières
3. Copiez la table des matières générée
4. Collez-la en haut du document, après le paragraphe d'introduction

Maintenir la synchronisation

La principale limitation est que le générateur ne met pas à jour automatiquement la table des matières quand vous modifiez le document. Si vous changez ou ajoutez des titres, vous devez régénérer et remplacer.

Pour les petits documents, ce n'est pas un problème. Pour les projets de documentation qui évoluent souvent, des options d'automatisation existent :

• doctoc (paquet npm) : met à jour la table des matières en place, idéal comme hook pre-commit
• Extensions VS Code : plusieurs extensions mettent à jour la table des matières automatiquement à la sauvegarde
• GitHub Actions : workflow configurable pour exécuter doctoc à chaque push

Le Générateur de table des matières est idéal pour une génération ponctuelle ou quand vous voulez vérifier exactement à quoi ressemble la sortie avant de la valider.

Outils complémentaires

Si vous travaillez beaucoup avec Markdown, quelques autres outils sur ce site méritent d'être connus.

L'outil Aperçu Markdown rend n'importe quel document Markdown en temps réel, pour confirmer visuellement comment les titres et la table des matières apparaîtront. Utile pour détecter les problèmes de formatage avant qu'ils ne se retrouvent dans un README publié.

Le convertisseur Markdown vers HTML est utile quand vous avez besoin de la sortie HTML réelle — par exemple pour coller dans un CMS qui accepte l'HTML mais pas le Markdown brut.

Le Générateur de tableau Markdown crée la syntaxe de tableau séparée par des pipes, notoirement pénible à écrire à la main.

Conseils pratiques

Commencez avec une hiérarchie de titres propre. Si votre document mélange H2 et H3 sans structure claire, la table des matières générée reflétera cette confusion. Le processus de génération révèle souvent des problèmes structurels qui étaient invisibles auparavant.

Les structures plates sont tout à fait valables. Un document avec uniquement des titres H2 produit une table des matières simple sans imbrication — c'est souvent exactement ce qu'il faut. Ne rajoutez pas de H3 juste pour que la table des matières paraisse plus élaborée.

Réfléchissez au mode de lecture de votre audience. Pour une documentation de référence API que les développeurs consultent régulièrement, une table des matières complète avec toute l'imbrication est utile. Pour un README qu'un nouvel utilisateur lira de haut en bas la première fois, une table des matières plus courte avec seulement les sections principales est souvent suffisante.

Automatiser les aspects mécaniques — génération des ancres, formatage des liens, indentation — vous permet de vous concentrer sur le contenu réel. C'est exactement l'objectif de cet outil.

Essayez le Générateur de table des matières Markdown pour votre prochain README ou fichier de documentation.