Ajouter un sommaire à un README GitHub
GitHub propose déjà un sommaire dans le menu « Plan » lorsqu’un fichier contient au moins deux titres, comme l’explique sa documentation sur les titres et le sommaire automatique. Ce menu appartient à l’interface GitHub ; il n’ajoute pas de liste de liens dans le texte du fichier.
Ce générateur de sommaire Markdown produit une liste de liens internes à coller dans le corps de votre README. Le sommaire fait ainsi partie du document et reste présent lorsque vous copiez son contenu ailleurs. Vous pouvez aussi l’utiliser pour une documentation technique ou un cours rédigé en Markdown ; vérifiez les liens dans le lecteur choisi.
Collez le document complet
Collez votre texte dans la zone « Votre document Markdown » ou ouvrez un fichier .md ou .markdown. Incluez tous les titres : deux sections portant le même nom peuvent recevoir des ancres différentes selon leur ordre dans le document.
Choisissez les niveaux de titres
Pour un README, sélectionnez par exemple H2 à H3 : le titre principal H1 reste hors du sommaire et les détails H4 à H6 ne l’encombrent pas. Les sous-titres sont automatiquement décalés dans la liste.
Vérifiez, copiez et collez
Cliquez sur les liens dans l’aperçu, puis sur « Copier le sommaire ». Dans votre éditeur, collez le résultat après la présentation du projet, avant la première grande section. Enregistrez le fichier et vérifiez les liens sur la plateforme où il sera lu.
Pour revoir aussi la mise en forme des listes, des tableaux et des blocs de code, ouvrez le document complet dans l’éditeur Markdown avec aperçu en temps réel. Cet aperçu ne remplace pas la vérification sur votre plateforme de publication.
Accents, apostrophes et titres identiques : un exemple en français
L’exemple préchargé montre comment cet outil construit ses ancres de style GitHub : les lettres passent en minuscules, les accents sont conservés, les espaces deviennent des traits d’union et les apostrophes sont retirées. Un suffixe distingue les titres identiques.
Voici les fragments attendus pour cet exemple, d’après les règles du générateur. Ils décrivent la sortie de cet outil ; le rendu de votre plateforme reste à vérifier.
La documentation GitHub sur les liens de section détaille les règles de nommage des ancres et les suffixes des titres identiques. Elle précise aussi qu’un changement de titre ou d’ordre peut nécessiter une mise à jour des liens.
| Titre dans le document | Cible du lien |
|---|---|
| Présentation | #présentation |
| Guide d’installation | #guide-dinstallation |
| Prérequis | #prérequis |
| Configuration — première occurrence | #configuration |
| Configuration — deuxième occurrence | #configuration-1 |
| Coûts et délais | #coûts-et-délais |
Mettre à jour le sommaire après avoir modifié les titres
Dans cette page, le sommaire se recalcule quand vous modifiez le texte ou les niveaux sélectionnés. La copie déjà collée dans votre fichier reste toutefois inchangée : l’outil ne réécrit pas votre README et ne se synchronise pas avec VS Code.
Pour actualiser votre document, retirez l’ancien sommaire du texte à coller ici, générez la nouvelle version, puis remplacez l’ancienne liste dans votre fichier. Cela évite de conserver des liens périmés ou d’inclure le titre « Sommaire » dans son propre contenu.
Un lien ne mène plus à la bonne section ?
Vérifiez d’abord si le titre a été renommé. Si plusieurs titres sont identiques, un changement d’ordre peut aussi modifier leurs suffixes. Régénérez le sommaire à partir du document complet plutôt que de corriger seulement le texte visible du lien.
Le lien fonctionne ici, mais pas sur votre site ?
Comparez sa cible avec l’identifiant de la section dans le document publié. Les règles d’ancrage dépendent du moteur de rendu. Cet outil propose un seul style d’ancres, sans réglage spécifique pour GitLab, Obsidian ou Pandoc.
Sur GitHub, survolez le titre de la section et utilisez son icône de lien pour récupérer l’ancre exacte. Pour préparer un lien isolé avec cette cible, utilisez le générateur de liens Markdown.
Comment mettre à jour automatiquement un sommaire dans VS Code ?
Si vous modifiez souvent votre README, l’extension Markdown All in One pour VS Code permet de créer un sommaire avec la commande « Create Table of Contents ». Elle le met ensuite à jour à chaque enregistrement par défaut ; ce comportement se règle avec markdown.extension.toc.updateOnSave.
Le générateur en ligne convient à une génération ponctuelle suivie d’un copier-coller. L’extension convient mieux si vous souhaitez maintenir le sommaire directement dans votre éditeur.
Questions pratiques sur le sommaire Markdown
Quelle différence entre une table des matières, un sommaire et une TOC ?
Sur cette page, les trois termes désignent la liste de liens vers les titres du document. TOC est l’abréviation de Table of Contents. Le résultat est un sommaire cliquable, sans numéros de page.
Comment ne garder que les titres H2 et H3 ?
Choisissez H2 dans « Du niveau » et H3 dans « Au niveau ». Le filtrage porte sur une plage de niveaux ; il ne permet pas de décocher un titre précis.
Les lignes commençant par # dans un bloc de code sont-elles incluses ?
Non, lorsqu’elles se trouvent dans un bloc de code Markdown correctement délimité. Le générateur analyse les titres du document, pas les lignes de vos exemples de code.
Peut-on créer une table des matières numérotée ?
Le résultat utilise une liste à puces avec des sous-niveaux. Il n’y a pas d’option de numérotation dans cet outil ; vous pouvez modifier la liste après l’avoir copiée dans votre éditeur.
Mon document est-il envoyé à un serveur ?
Le fichier est lu et le sommaire est généré dans votre navigateur, sans envoi du texte à un serveur pour ce traitement. Le texte est aussi conservé dans le stockage de session du navigateur pour le retrouver lors d’un rechargement dans le même onglet. Aucun compte n’est nécessaire.
Comment ajouter un sommaire natif dans GitLab ?
Dans GitLab, placez [[_TOC_]] ou [TOC] sur une ligne distincte pour afficher un sommaire généré par la plateforme. La documentation GitLab sur les tables des matières indique les contenus pris en charge : fichiers Markdown, pages wiki et descriptions d’issues, de merge requests ou d’epics, mais pas les notes ni les commentaires.
Ces marqueurs sont propres à GitLab et ne constituent pas une syntaxe Markdown universelle. Utilisez-les pour un document lu dans GitLab ; si vous préférez une liste de liens écrite dans le fichier, copiez le sommaire généré ici et vérifiez ses ancres dans le rendu final.
Le sommaire fonctionne-t-il dans tous les lecteurs Markdown ?
Les liens générés utilisent des ancres de style GitHub. Leur fonctionnement dépend des identifiants créés par votre lecteur Markdown : vérifiez les sauts de section dans le rendu final, notamment pour les titres accentués ou répétés.