De eerste keer dat een README van mij duizend lijnen overschreed, deed ik wat iedereen doet: ik scrolde Daarna scrolde ik nog wat meer Ergens rond de vierde pas op zoek naar de & quot; Deployment" sectie, gaf ik het op en begon met de hand een inhoudsopgave te schrijven bovenaan het bestand Dat werkte totdat ik een kop hernoemde, vergat de link bij te werken en een README verscheepte waar & quot; Configuration" naar niets wees Een verbroken link in pagina in je eigen documentatie is een kleinigheid, maar het is het soort kleinigheidje dat een lezer vertelt dat niemand zich met de winkel bemoeit.
Ik bouw [Toolz.dev] (/, een verzameling van browser-gebaseerde ontwikkelaarshulpprogramma's, en ik onderhoud veel Markdown: gereedschapsgidsen, README-bestanden, interne specificaties en de documenten die u nu leest Een inhoudsopgave die ik met de hand moet onderhouden is een inhoudsopgave die uiteindelijk zal liggen Dus heb ik de Markdown TOC Generator om het saaie deel elke keer correct te doen, en deze gids is alles wat ik heb geleerd over ankerlinks tijdens het bouwen ervan.
tl;dr: Een Markdown inhoudsopgave is een geneste lijst van links die naar koppen op dezelfde pagina springen De koppelingen werken omdat elke kop een automatische anker-ID krijgt, en de slug die GitHub toekent volgt een specifieke regel: kleine letters in de tekst, leestekens laten vallen anders dan koppeltekens, en spaties in koppeltekens veranderen Plak je Markdown in de generator, kies welke kopniveaus je wilt opnemen en kopieer de lijst Het hulpmiddel berekent de exacte slugs GitHub-weergaven, inclusief de
-1achtervoegsel voor dubbele koppen, dus er gaat niets kapot als je het terug plakt.
Wat is een Markdown inhoudsopgave?
Een inhoudsopgave in Markdown is geen speciale syntaxis. gemeenschappelijke markering definieert een dergelijke constructie niet, en GitHub Flavored Markdown ook niet Het is een gewone lijst waarbij elk item een link is, en elke link naar een anker in hetzelfde document wijst Wanneer een Markdown-renderer zoals GitHub een kop in HTML verandert, geeft het ook die kop een id attribuut. Een kop geschreven als ## Getting Started ruw wordt <h2 id="getting-started">Getting Started</h2>. Zodra die id bestaat, wordt een link geschreven als [Getting Started](#getting-started) scrollt de pagina ernaar.
Een inhoudsopgave is dus slechts een verzameling van die links, ingesprongen om de kophiërarchie te weerspiegelen:
- [Getting Started](#getting-started)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
De hele truc leeft in één woord uit dat voorbeeld: het anker Verkrijg het anker en de link mislukt stilletjes, scrolt nergens. Krijg het goed en het inhoudsblok werkt op GitHub, in de meeste generatoren op statische locaties en in documentatieplatforms die dezelfde conventie volgen. Het moeilijkste is om de lijst niet te schrijven. Het moeilijkste is het voorspellen van de exacte id die elke renderer zal toewijzen. Daarom is het met de hand doen een verloren spel op elk document dat verandert.
Hoe worden koersankers eigenlijk gegenereerd?
GitHub's slug algoritme is deterministisch en de moeite waard om te onthouden, want als je het eenmaal weet kun je elk anker op de pagina voorspellen De stappen zijn in volgorde: converteer de koptekst naar kleine letters, verwijder elk teken dat geen letter, een getal, een spatie of een koppelteken is, en vervang vervolgens elke spatie door een koppelteken Dat is de hele regel.
De gevolgen zijn waar mensen naartoe reizen Overweeg een kopje als ## Set Up & Config. Ondermantel geeft set up & config. Het verwijderen van het ampersand (maar het verlaten van de ruimtes eromheen) geeft set up config met twee ruimtes waar de & vroeger Spaties in koppeltekens veranderen levert set-up--config, met een dubbel koppelteken Dat dubbele koppelteken ziet eruit als een vergissing, maar het is precies wat GitHub weergeeft, dus het is precies wat uw link nodig heeft Een tool die " opruimt" het dubbele koppelteken zou een link opleveren die niet oplost.
Interpunctie-zware koppen vallen verder in elkaar dan je verwacht. ## C++ Guide HALD c-guide, omdat beide plustekens worden gestript en de overgebleven ruimte één enkel koppelteken wordt. ## What's New? HALD whats-new, omdat de apostrof en het vraagteken verdwijnen Emoji en de meeste symbolen verdwijnen geheel De Markdown TOC Generator past dit regelteken toe voor een personage, zodat de slug laat zien dat dit de id is die GitHub zal bouwen, zonder dat er sprake is van gissen.
Wat gebeurt er als twee kopjes hetzelfde zijn?
Documenten herhalen kopjes Een changelog kan uit drie secties bestaan, allemaal getiteld ### Fixed. Als ze allemaal de slug hebben geproduceerd fixed, alleen de eerste link zou werken GitHub lost dit op door de duplicaten te nummeren: de eerste Fixed krijgt fixed, de tweede krijgt fixed-1, de derde krijgt fixed-2, enzovoort in documentvolgorde Het achtervoegsel wordt met een koppelteken achter de basis slug toegevoegd.
Dit is een van de meest voorkomende redenen waarom een handgeschreven inhoudsopgave niet synchroon loopt Je voegt een tweede sectie toe met een naam die je al hebt gebruikt, het anker wordt stilletjes -1, en je oude link wijst nu op de verkeerde plaats of helemaal nergens. De generator volgt elke slug die hij heeft uitgezonden en past hetzelfde numerieke achtervoegsel toe, dus herhaalde koppen linken naar de juiste gebeurtenis.
Wat voor soort kopjes leest de tool?
Markdown heeft twee kopstijlen, en een complete generator moet beide lezen De gebruikelijke is ATX, waarbij een lijn begint met één tot zes # tekens gevolgd door de koptekst Het aantal hashes is het niveau, dus # is een H1 en ###### is een H6. de tweede stijl is Setext, waarbij op de volgende regel een regel tekst wordt onderstreept met gelijktekens voor een H1 of koppeltekens voor een H2:
Document Title
==============
A Section
---------
Beide stijlen produceren koppen met anker-ID's, dus beide horen thuis in een inhoudsopgave Het lastige deel met Setext is het vertellen van een echte onderstreepte kop, afgezien van een horizontale regel, omdat een regel koppeltekens een van beide kan betekenen De regel die de generator gebruikt is dat een onderstreping met koppelteken alleen als kop telt als de regel er direct boven gewone alinea-tekst is, en niet een lege regel, een lijstitem, een blokquote of een andere blokconstructie. Een --- alleen zitten met lege lijnen eromheen is een thematische pauze, en deze wordt terecht genegeerd.
Er is nog een categorie om te hanteren, en het is degene die stilletjes naïeve tools verpest: kopjes binnen code Als uw document een omheind codeblok bevat dat shell-opdrachten toont, zullen sommige van die regels beginnen met # als commentaar Dat zijn geen kopjes, en ze mogen nooit in de inhoud voorkomen De generator volgt omheinde codeblokken (die worden begrensd door drievoudige backticks of drievoudige tildes) en slaat deze over # lijn erin Een shell comment als # install dependencies in een voorbeeld blijft waar het thuishoort, in het voorbeeld.
Hoe regel ik de diepte van de inhoudsopgave?
Een inhoudsopgave waarin elke rubriek tot H6 wordt vermeld, is geen inhoudsopgave, het is een tweede kopie van het document De meeste README's lezen het beste wanneer de inhoud alleen betrekking heeft op H2 en H3, waardoor lezers de belangrijkste secties en hun directe kinderen krijgen zonder ze in detail te verdrinken. Met de generator kunt u een minimum- en een maximumniveau instellen, en deze bevat alleen de kopjes die binnen dat bereik vallen.
Het subtiele gedrag hier is inspringen Als je H2 tot en met H4 meetelt, is de ondiepste koers die je hebt aangehouden een H2, en deze moet vlak tegen de linkermarge zitten in plaats van ingesprongen alsof er een onzichtbare H1 boven zit. De generator meet de nestdiepte ten opzichte van de ondiepste koers die hij feitelijk bevat, dus een inhoudsblok dat begint bij H2 begint zonder inspringen. Dit is het verschil tussen een lijst die er opzettelijk uitziet en een lijst die eruitziet alsof hij zijn eerste kolom heeft verloren.
U krijgt ook de lijstmarkering te kiezen Een ongeordende lijst gebruikt een bullet voor elke invoer, dat is de conventionele look voor een README Een geordende lijst nummert de vermeldingen, en de generator herstart de telling binnen elk nestniveau zodat een genummerde omtrek correct leest in plaats van rechtstreeks te tellen van één tot vijftig Inspringing kan twee spaties, vier spaties, of een tabblad zijn, afhankelijk van wat de rest van uw document gebruikt.
Hoe zit het met geaccentueerde en niet-Latijnse kopjes?
Niet elke kop is gewoon Engels, en de slug-regel moet het hoofd bieden. GitHub bewaart letters van andere alfabetten in plaats van ze te verwijderen, dus een kop als ## Configuración behoudt zijn accenten karakters en wordt configuración, en een kop in het Cyrillisch of Grieks bewaart die letters ook. Wat wordt verwijderd zijn interpunctie en symbolen, geen letters, ongeacht het script. De generator volgt hetzelfde principe door elke Unicode-letter of cijfer te behandelen als een geldig slug-teken, dus een meertalig document produceert ankers die overeenkomen met wat GitHub weergeeft in plaats van een rij lege links.
Dit is belangrijker dan het op het eerste gezicht lijkt Teams die documentatie in het Spaans, Duits of Japans schrijven, vinden vaak dat naïeve slug-tools hun kopjes verminken tot onbruikbare ankers, omdat die tools ASCII aannemen. Als uw links ooit op niets hebben gewezen op een vertaalde README, is een slug die in stilte de niet-ASCII-letters heeft weggegooid vrijwel zeker de reden. Het genereren van het inhoudsblok met een Unicode-bewuste tool verwijdert die hele klasse verbroken links, en het betekent dat hetzelfde document koppen in meer dan één taal kan bevatten zonder dat een van hen zijn ankers verliest.
Wanneer moet ik een gegenereerde TOC gebruiken versus een automatische?
Sommige platforms bouwen een inhoudsopgave voor u GitLab ondersteunt een [[_TOC_]] token, sommige wiki's injecteren automatisch een inhoudsvak, en documentatieframeworks zoals Docusaurus geven een overzicht op de pagina weer uit uw koppen zonder dat u iets schrijft Wanneer u binnen een van die systemen werkt, gebruikt u de ingebouwde functie. Het blijft zonder enige inspanning actueel omdat het platform het op elke render regenereert.
De generator verdient zijn plaats overal elders, en & quot; overal elders" is een grote plaats GitHub README's genereren niet automatisch een inhoudblok, dus een landingspagina van een repository heeft een echte Markdown-lijst nodig die in het bestand is vastgelegd Markdown die naar iets anders wordt geconverteerd, gemaild, in een probleem geplakt of door een minimale viewer wordt weergegeven, heeft een statisch inhoudsblok nodig omdat er geen engine is om er direct een te bouwen. In de onderstaande tabel wordt aangegeven waar elke aanpak past.
| betrekking | Beste aanpak | waarom |
|---|---|---|
| GitHub README | Gegenereerde statische lijst | GitHub geeft kop-ID's weer, maar voegt niet automatisch een TOC in |
| GitLab-wiki of documenten | [[_TOC_]] token |
Inheems, altijd actueel |
| Docusaurus / MkDocs-pagina | Ingebouwde omtrek | Framework geeft het weer uit kopjes |
| Plain Markdown-bestand voor export | Gegenereerde statische lijst | Geen renderer om er een te bouwen tijdens het bekijken |
| Beschrijving van aanvraag voor uitgifte of pull | Gegenereerde statische lijst | Ankers werken, maar niets genereert de lijst automatisch |
De vuistregel: als het ding dat uw Markdown weergeeft de inhoud zelf kan opbouwen, laat het dan Als uw Markdown ergens gelezen kan worden waar dat niet kan, genereer dan de lijst en verbind deze. Wanneer u tussen formaten converteert, zal de Markdown naar HTML-converter en de HTML naar Markdown converter combineer op natuurlijke wijze met een gegenereerd inhoudsblok, omdat de ankers de retour overleven.
Hoe past dit bij de rest van een Markdown workflow?
Een inhoudsopgave is een stukje lange documenten leesbaar houden, en het werkt het beste naast een paar gewoontes Houd je koptekst stabiel zodra je er links naar hebt gepubliceerd, want het hernoemen van een kop verandert de slug en verbreekt elke link die ernaar wees Wanneer je de naam hernoemt, regenereer dan de ene link die je je herinnert te bewerken, aangezien een hernoeming vaak de nummering van dubbele achtervoegsels verder in het bestand verschuift.
Gestructureerde inhoud profiteert van andere tools in dezelfde familie Wanneer een document leunt op tabelgegevens, kan de Markdown-tabelgenerator bouwt correct uitgelijnde pijptabellen die een handgetypte tabel bijna nooit goed krijgt Wanneer u rommelige HTML erft die clean Markdown moet worden, of Markdown opschonen die HTML moet worden, verwerken de converters de vertaling met behoud van de kopstructuur En als u een document controleert op lengte of trefwoordbalans, de woord teller geeft u de cijfers zonder uw concept in iets cloudgebaseerds te plakken.
Alles draait in de browser, wat er meer toe doet dan het klinkt Een README bevat vaak niet vrijgegeven functienamen, interne URL's of clientgegevens, en niets daarvan mag worden geüpload naar een server van derden alleen maar om een lijst met links op te bouwen. De generator parseert uw Markdown met JavaScript aan de clientzijde, zodat het document uw machine nooit verlaat. Als privacy bij ontwikkelaarstools iets is waar u aan denkt, wordt er geschreven Gegevensprivacy en online tools dekt waarom lokale verwerking de juiste standaard is, en de Webontwikkelaar Toolkit rondt de rest van de nutsvoorzieningen af waar ik dagelijks naar toe reik.
Een snel uitgewerkt voorbeeld
Stel dat u dit document heeft
# Payment Service
## Getting Started
### Requirements
### Local Setup
## API Reference
### Authentication
### Errors
## Deployment
Stel het bereik in op H2 tot en met H3, kies een lijst met opsommingstekens en laat ankerlinks aan. De generator produceert
- [Getting Started](#getting-started)
- [Requirements](#requirements)
- [Local Setup](#local-setup)
- [API Reference](#api-reference)
- [Authentication](#authentication)
- [Errors](#errors)
- [Deployment](#deployment)
De H1-titel is uitgesloten omdat deze boven het bereik ligt, de H2-secties zijn links verzonken en hun H3-kinderen zijn één niveau ingesprongen. Plak dat blok net onder de titel in je README en elke invoer springt naar de sectie op GitHub. Dat is de hele klus, gedaan in de tijd die nodig is om deze zin te lezen, en het blijft correct omdat een machine de slugs berekende in plaats van jij.
Veelgestelde vragen
Hoe werkt een Markdown inhoudsopgave?
Een Markdown inhoudsopgave is een lijst met links die verwijzen naar kopankers binnen dezelfde pagina Elke kop in een Markdown-document krijgt een automatische id, en een link geschreven als Sectie springt er naar toe Deze tool leest uw kopjes, bouwt de bijpassende ankers, en stelt de geneste lijst voor u samen.
Hoe worden de ankerlinks gegenereerd?
Ankers volgen de GitHub slug-regel: de koptekst is lager, interpunctie anders dan koppeltekens wordt verwijderd en spaties worden koppeltekens. " Zet & amp; Config" wordt de id-opstelling-config. Wanneer twee koppen dezelfde slug produceren, krijgt de tweede een -1-achtervoegsel, de derde -2, enzovoort, wat overeenkomt met hoe GitHub ze weergeeft.
Werkt het met GitHub README-bestanden?
Ja. Het slug-algoritme weerspiegelt het algoritme dat GitHub gebruikt om kop-ID's weer te geven, dus de koppelingen in de inhoudsopgave worden correct opgelost in een README op github.com. Plakken van uw README, kies uw kopniveaus en laat de gegenereerde lijst onder de titel vallen.
Kan ik kiezen welke kopniveaus verschijnen?
Ja Stel een minimum en maximum niveau in, bijvoorbeeld H2 tot en met H4, en alleen koppen in dat bereik zijn inbegrepen De nestdiepte wordt gemeten ten opzichte van de ondiepste meegeleverde kop, dus de omtrek begint nooit met een grote lege inspringing.
Zijn kopjes binnen codeblokken inbegrepen?
Geen. Regels die beginnen met # binnen een omheind codeblok (afgegrensd door drievoudige backticks of drievoudige tildes) worden behandeld als code, niet als koppen, dus voorbeeldfragmenten en shell-opmerkingen verschijnen nooit in de inhoudsopgave.
Wat is het verschil tussen een geordende en ongeordende TOC?
Een ongeordende inhoudsopgave gebruikt voor elke invoer opsommingstekens zoals een koppelteken, terwijl een geordende opsomming getallen gebruikt die binnen elk nestniveau toenemen Kies geordend wanneer lezers profiteren van een genummerde omtrek, en ongeordend voor een lichter, meer conventioneel inhoudsblok.
Ondersteunt de tool Setext-koppen?
Ja. het leest zowel ATX-koppen die beginnen met #- als Setext-koppen, waarbij een regel tekst wordt onderstreept met gelijke tekens voor H1 of koppeltekens voor H2. Beide stijlen worden op dezelfde manier omgezet in ankerlinks.
Is de Markdown TOC generator gratis en privé?
Ja. Het is volledig gratis zonder aanmelding en zonder limieten. Alle parsering vindt plaats in uw browser met behulp van JavaScript aan de clientzijde, dus de Markdown die u plakt verlaat uw apparaat nooit en de tool blijft offline werken zodra de pagina is geladen.
