La première fois qu'un README de moi a franchi mille lignes, j'ai fait ce que tout le monde fait : J'ai fait défiler Puis j'en ai fait défiler encore un peu Vers le quatrième passage à la recherche de la section " ; Déploiement" ;, j'ai abandonné et j'ai commencé à écrire à la main une table des matières en haut du fichier Cela a fonctionné jusqu'à ce que je renomme un en-tête, que j'oublie de mettre à jour le lien, et que j'ai expédié un README où " ; Configuration" ; n'a rien pointé Un lien cassé dans la page de votre propre documentation est une petite chose, mais c'est le genre de petite chose, mais c'est le genre de petite chose, c'est le genre de petite chose qui dit à un lecteur que personne ne s'est que cela ne s'est que cela ne s'intéresse au magasin.
Je construis [Toolz.dev] (/, une collection d'utilitaires de développement basés sur un navigateur, et je maintiens beaucoup de Markdown : guides d'outils, fichiers README, spécifications internes et documents que vous lisez en ce moment. Une table des matières que je dois tenir à la main est une table des matières qui finira par mentir J'ai donc construit le Générateur de TOC Markdown pour faire la partie ennuyeuse correctement à chaque fois, et ce guide est tout ce que j'ai appris sur les liens d'ancrage lors de sa construction.
tl;dr : Une table des matières Markdown est une liste imbriquée de liens qui sautent vers des titres sur la même page Les liens fonctionnent car chaque titre obtient un identifiant d'ancrage automatique, et le slug que GitHub attribue suit une règle spécifique : minuscule le texte, drop ponctuation autre que les tirets, et transformer les espaces en tirets Collez votre Markdown dans le générateur, choisissez quels niveaux de titre inclure, et copiez la liste L'outil calcule les rendus exacts de slugs GitHub, y compris le
-1suffixe pour les titres en double, donc rien ne se casse lorsque vous le collez en arrière.
Qu'est-ce qu'une table des matières Markdown ?
Une table des matières dans Markdown n'est pas une syntaxe spéciale. marque courante ne définit pas une telle construction, et GitHub Flavored Markdown non plus C'est une liste ordinaire où chaque élément est un lien, et chaque lien pointe vers un ancrage à l'intérieur du même document Quand un moteur de rendu Markdown comme GitHub transforme un en-tête en HTML, il donne aussi à ce en-tête un id attribut. Un titre écrit comme ## Getting Started devient grossièrement <h2 id="getting-started">Getting Started</h2>. Une fois que cet identifiant existe, un lien écrit comme [Getting Started](#getting-started) fait défiler la page vers elle.
Une table des matières n'est donc qu'une collection de ces liens, en retrait pour refléter la hiérarchie des titres :
- [Getting Started](#getting-started)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
L'intégralité de l'astuce vit en un mot de cet exemple : l'ancre Se tromper d'ancre et le lien échoue silencieusement, ne défilant nulle part Obtenez-le correctement et le bloc de contenu fonctionne sur GitHub, dans la plupart des générateurs de sites statiques, et à l'intérieur des plates-formes de documentation qui suivent la même convention La partie dure est de ne pas écrire la liste La partie dure est de prédire l'id exact que chaque moteur de rendu attribuera, c'est pourquoi le faire à la main est une partie perdante sur tout document qui change.
Comment les ancrages de cap sont-ils réellement générés ?
GitHub' ; s slug algorithme est déterministe et mérite d'être mémorisé, car une fois que vous le savez, vous pouvez prédire chaque ancre sur la page Les étapes, dans l'ordre, sont : convertir le texte de l'en-tête en minuscules, supprimer tout caractère qui n'est pas une lettre, un nombre, un espace, ou un trait d'union, et ensuite remplacer chaque espace par un trait d'union C'est toute la règle.
Les conséquences sont l'endroit où les gens voyagent Considérez un cap comme ## Set Up & Config. Le casse inférieur donne set up & config. Retirer l'esperluette (mais en laissant les espaces autour) donne set up config avec deux espaces où le & autrefois. Transformer les espaces en traits d’union produit set-up--config[TRADUCTION], avec un double tiret Ce double tiret ressemble à une erreur, mais c'est exactement ce que GitHub rend, donc c'est exactement ce dont votre lien a besoin Un outil que " ; nettoie vers le haut" ; le double tiret produirait un lien qui ne résout pas.
Les titres à forte ponctuation s’effondrent plus que prévu. ## C++ Guide se transforme c-guide4, car les deux signes plus sont supprimés et l’espace restant devient un seul trait d’union. ## What's New? se transforme whats-new, parce que l'apostrophe et le point d'interrogation disparaissent Emoji et la plupart des symboles disparaissent entièrement Le Générateur de TOC Markdown applique ce caractère de règle pour le caractère donc le slug il vous montre est l'identifiant que GitHub va construire, aucune supposition impliquée.
Que se passe-t-il lorsque deux titres sont identiques ?
Les documents reprennent les titres Un journal des modifications peut comporter trois sections toutes intitulées ### Fixed. Si chacun d'eux a produit le slug fixed[TRADUCTION], seul le premier lien fonctionnerait GitHub résout cela en numérotant les doublons : le premier Fixed obtient fixed[TRADUCTION], la seconde obtient fixed-1[TRADUCTION], le troisième obtient fixed-2_, et ainsi de suite dans l'ordre des documents Le suffixe est ajouté après la base slug avec un trait d'union.
C'est l'une des raisons les plus courantes pour lesquelles une table des matières manuscrite dérive de manière désynchronisée. Vous ajoutez une deuxième section avec un nom que vous avez déjà utilisé, l'ancre devient discrètement -1_, et votre ancien lien pointe maintenant au mauvais endroit ou nulle part du tout Le générateur suit chaque slug qu'il a émis et applique le même suffixe numérique, donc les titres répétés renvoient à la bonne occurrence.
Quels types de titres l’outil lit-il ?
Markdown a deux styles de titre, et un générateur complet doit lire les deux Le commun est ATX, où une ligne commence par un à six # caractères suivis du texte de titre Le nombre de hachages est le niveau, donc # est un H1 et ###### est un H6. Le deuxième style est Setext, où une ligne de texte est soulignée sur la ligne suivante avec des signes égaux pour un H1 ou des tirets pour un H2 :
Document Title
==============
A Section
---------
Les deux styles produisent des titres avec des identifiants d'ancrage, donc les deux appartiennent à une table des matières La partie délicate avec Setext est de dire un vrai cap souligné en dehors d'une règle horizontale, car une ligne de tirets peut signifier soit La règle utilisée par le générateur est qu'un soulignement de trait d'union ne compte comme un titre que lorsque la ligne directement au-dessus est un texte de paragraphe ordinaire, pas une ligne blanche, un élément de liste, un blockquote ou une autre construction de bloc. UN --- rester seul avec des lignes blanches autour de lui est une pause thématique, et elle est correctement ignorée.
Il y a encore une catégorie à gérer, et c'est celle qui ruine tranquillement les outils naïfs : les titres à l'intérieur du code Si votre document contient un bloc de code clôturé qui affiche les commandes shell, certaines de ces lignes commenceront par # comme commentaires Ce ne sont pas des en-têtes, et ils ne doivent jamais apparaître dans le contenu Le générateur suit des blocs de code clôturés (ceux délimités par des backticks triples ou des tildes triples) et en saute # ligne à l'intérieur d'eux Un commentaire shell comme # install dependencies dans un exemple reste à sa place, dans l'exemple.
Comment contrôler la profondeur de la table des matières ?
Une table des matières qui répertorie chaque cap jusqu'à H6 n'est pas une table des matières, c'est une deuxième copie du document La plupart des README lisent mieux lorsque le contenu couvre H2 et H3 seulement, donnant aux lecteurs les sections principales et leurs enfants immédiats sans les noyer en détail Le générateur vous permet de définir un niveau minimum et un niveau maximum, et il comprend uniquement les rubriques qui se situent dans cette plage.
Le comportement subtil ici est l'indentation Si vous incluez H2 à H4, le cap le moins profond que vous avez gardé est un H2, et il devrait reposer au ras de la marge gauche plutôt qu'en retrait comme si un H1 invisible était au-dessus. Le générateur mesure la profondeur d'imbrication par rapport au cap le moins profond qu'il comprend réellement, donc un bloc de contenu qui commence à H2 commence sans retrait. C'est la différence entre une liste qui semble intentionnelle et une liste qui semble avoir perdu sa première colonne.
Vous pouvez également choisir le marqueur de liste Une liste non ordonnée utilise une puce pour chaque entrée, qui est le look conventionnel pour un README Une liste ordonnée numérote les entrées, et le générateur redémarre le compte dans chaque niveau d'imbrication pour qu'un contour numéroté se lise correctement plutôt que de compter directement de un à cinquante. L'indentation peut être de deux espaces, quatre espaces ou un onglet, selon ce qu'utilise le reste de votre document.
Qu'en est-il des rubriques accentuées et non latines ?
Tous les titres ne sont pas en anglais simple et la règle slug doit s'en sortir. GitHub conserve les lettres des autres alphabets plutôt que de les supprimer, donc un titre comme ## Configuración garde ses caractères accentués et devient configuración« , et un titre en cyrillique ou en grec conserve également ces lettres. Ce qui est supprimé, c'est la ponctuation et les symboles, pas les lettres, quel que soit le script. Le générateur suit le même principe en traitant n'importe quelle lettre ou chiffre Unicode comme un caractère slug valide, donc un document multilingue produit des ancres qui correspondent à ce que GitHub restitue plutôt qu'une rangée de liens vides.
Cela compte plus qu'il n'apparaît d'abord Les équipes qui écrivent de la documentation en espagnol, allemand ou japonais trouvent souvent que les outils naïfs slug mutilent leurs titres en ancres inutilisables, car ces outils supposent ASCII. Si vos liens n'ont jamais rien pointé sur un README traduit, un slug qui a silencieusement écarté les lettres non-ASCII est presque certainement la raison pour laquelle Générer le bloc de contenu avec un outil compatible Unicode supprime toute cette classe de lien rompu, et cela signifie que le même document peut contenir des titres dans plus d'une langue sans qu'aucun d'entre eux ne perde ses ancres.
Quand dois-je utiliser un COT généré par rapport à un COT automatique ?
Certaines plateformes construisent une table des matières pour vous GitLab supporte un [[_TOC_]] token, certains wikis injectent une zone de contenu automatiquement, et les frameworks de documentation comme Docusaurus rendent un contour sur la page à partir de vos titres sans que vous écriviez quoi que ce soit Lorsque vous travaillez à l'intérieur de l'un de ces systèmes, utilisez la fonction intégrée Il reste actuel avec zéro effort car la plate-forme le régénère sur chaque rendu.
Le générateur gagne sa place partout ailleurs, et " ; partout ailleurs" ; est un grand endroit Les GitHub README ne génèrent pas automatiquement un bloc de contenu, donc une page de destination de référentiel a besoin d'une véritable liste de Markdown engagée dans le fichier Le Markdown qui est converti en autre chose, envoyé par courrier électronique, collé dans un problème ou rendu par un visualiseur minimal a besoin d'un bloc de contenu statique car il n'y a pas de moteur pour en construire un à la volée Le tableau ci-dessous indique où chaque approche s'adapte.
| situation | Meilleure approche | pourquoi |
|---|---|---|
| GitHub README | Liste statique générée | GitHub restitue les identifiants de cap mais n'insère pas automatiquement un COT |
| Wiki ou docs GitLab | [[_TOC_]] jeton |
Natif, toujours actuel |
| Page Docusaurus/MkDocs | Plan intégré | Framework le rend à partir de titres |
| Fichier Markdown simple pour l'exportation | Liste statique générée | Aucun moteur de rendu pour en construire un au moment de la visualisation |
| Description de la demande d'émission ou de traction | Liste statique générée | Les ancres fonctionnent, mais rien ne génère automatiquement la liste |
La règle empirique : si la chose qui affiche votre Markdown peut construire le contenu lui-même, laissez-le Si votre Markdown peut être lu quelque part qui ne peut pas, générez la liste et commettez-la Lorsque vous êtes en train de convertir entre les formats, le Convertisseur de Markdown en HTML et le convertisseur HTML à Markdown associez naturellement à un bloc de contenu généré, car les ancres survivent à l'aller-retour.
Comment cela s'adapte-t-il au reste d'un flux de travail Markdown ?
Une table des matières est une pièce de garder les documents longs lisibles, et elle fonctionne mieux à côté de quelques habitudes Gardez votre texte de cap stable une fois que vous avez publié des liens vers elle, car renommer un en-tête change son slug et casse chaque lien qui pointait vers elle Lorsque vous renommez, régénérez le contenu plutôt que de modifier le seul lien dont vous vous souvenez, puisqu'un renom déplace souvent la numérotation des suffixes en double plus bas dans le fichier.
Le contenu structuré bénéficie d'autres outils de la même famille Lorsqu'un document s'appuie sur des données tabulaires, le Générateur de tables de démar construit des tables de tuyaux correctement alignées qu'une table typée à la main ne réussit presque jamais Lorsque vous héritez du HTML désordonné qui doit devenir un Markdown propre, ou un Markdown propre qui doit devenir HTML, les convertisseurs gèrent la traduction tout en préservant la structure de l'en-tête Et si vous vérifiez un document pour la longueur ou l'équilibre des mots clés, le compteur de mots vous donne les chiffres sans coller votre brouillon dans quoi que ce soit basé sur le cloud.
Tout s'exécute dans le navigateur, ce qui compte plus que ce qu'il sonne Un README contient souvent des noms de fonctionnalités inédits, des URL internes ou des détails clients, et rien de tout cela ne doit être téléchargé sur un serveur tiers juste pour construire une liste de liens Le générateur analyse votre Markdown avec JavaScript côté client, de sorte que le document ne quitte jamais votre machine Si la confidentialité dans l'outillage des développeurs est quelque chose auquel vous pensez, l'écriture sur Protection des données et outils en ligne couvre pourquoi le traitement local est la bonne valeur par défaut, et le Boîte à outils pour les développeurs Web rassemble le reste des utilitaires que j'atteins quotidiennement.
Un exemple qui a fonctionné rapidement
Supposons que vous ayez ce document :
# Payment Service
## Getting Started
### Requirements
### Local Setup
## API Reference
### Authentication
### Errors
## Deployment
Réglez la plage sur H2 à H3, choisissez une liste à puces et laissez les liens d'ancrage. Le générateur produit :
- [Getting Started](#getting-started)
- [Requirements](#requirements)
- [Local Setup](#local-setup)
- [API Reference](#api-reference)
- [Authentication](#authentication)
- [Errors](#errors)
- [Deployment](#deployment)
Le titre H1 est exclu car il se situe au-dessus de la plage, les sections H2 affleurent à gauche et leurs enfants H3 sont échancrés d'un niveau Collez ce bloc juste sous le titre dans votre README et chaque entrée passe à sa section sur GitHub. C'est tout le travail, fait dans le temps qu'il faut pour lire cette phrase, et cela reste correct car une machine a calculé le slugs à votre place.
Questions fréquentes
Comment fonctionne une table des matières Markdown ?
Une table des matières Markdown est une liste de liens qui pointent vers des ancres de titre dans la même page Chaque titre d'un document Markdown reçoit un identifiant automatique et un lien écrit comme suit Section saute à elle Cet outil lit vos titres, construit les ancres correspondantes, et assemble la liste imbriquée pour vous.
Comment les liens d'ancrage sont-ils générés ?
Les ancres suivent la règle GitHub slug : le texte de l'en-tête est en minuscules, la ponctuation autre que les tirets est supprimée et les espaces deviennent des tirets. " ; Définir & amp ; Config" ; devient l'identifiant set-up-config. Lorsque deux en-têtes produisent le même slug, le second obtient un suffixe -1, le troisième -2, et ainsi de suite, correspondant à la façon dont GitHub les restitue.
Fonctionne-t-il avec les fichiers GitHub README ?
Oui. L'algorithme slug reflète celui que GitHub utilise pour restituer les identifiants de titre, afin que les liens de la table des matières se résolvent correctement dans un README sur github.com. Collez votre README, choisissez vos niveaux de titre et déposez la liste générée sous le titre.
Puis-je choisir quels niveaux de titre apparaissent ?
Oui. Fixez un niveau minimum et maximum, par exemple H2 à H4, et seuls les titres de cette plage sont inclus. La profondeur de nidification est mesurée par rapport au cap inclus le moins profond, de sorte que le contour ne commence jamais par un grand retrait vide.
Les titres à l'intérieur des blocs de code sont-ils inclus ?
Non. Les lignes qui commencent par # à l'intérieur d'un bloc de code clôturé (délimité par des backticks triples ou des tildes triples) sont traitées comme du code et non comme des titres, donc les exemples d'extraits et de commentaires shell n'apparaissent jamais dans la table des matières.
Quelle est la différence entre un TOC ordonné et non ordonné ?
Une table des matières non ordonnée utilise des marqueurs de puces tels qu'un trait d'union pour chaque entrée, tandis qu'une ordonnée utilise des nombres qui s'incrémentent à l'intérieur de chaque niveau d'imbrication Choisissez ordonné lorsque les lecteurs bénéficient d'un contour numéroté, et non ordonné pour un bloc de contenu plus léger et plus conventionnel.
L'outil prend-il en charge les titres Setext ?
Oui. Il lit les deux en-têtes ATX qui commencent par les en-têtes # et Setext, où une ligne de texte est soulignée avec des signes égaux pour H1 ou des tirets pour H2. Les deux styles sont convertis en liens d'ancrage de la même manière.
Le générateur Markdown TOC est-il gratuit et privé ?
Oui. Il est entièrement gratuit sans inscription ni limite. Toute analyse a lieu dans votre navigateur à l'aide de JavaScript côté client, de sorte que le Markdown que vous collez ne quitte jamais votre appareil et que l'outil continue de fonctionner hors ligne une fois la page chargée.
