Als ein README von mir zum ersten Mal tausend Zeilen überschritt, tat ich, was alle tun: Ich scrollte dann noch etwas weiter Irgendwo um den vierten Durchgang herum, auf der Suche nach dem " Deployment" Abschnitt, gab ich auf und begann, oben in der Datei ein Inhaltsverzeichnis von Hand zu schreiben Das funktionierte, bis ich eine Überschrift umbenannte, vergaß, den Link zu aktualisieren, und einen README verschickte, bei dem " Configuration" auf nichts hinwies Ein defekter In-Page-Link in der eigenen Dokumentation ist eine Kleinigkeit, aber es ist die Art Kleinigkeit, die einem Leser sagt, dass sich niemand um den Laden kümmert.
Ich baue [Toolz.dev] (/, eine Sammlung von browserbasierten Entwickler-Dienstprogrammen, und ich betreue eine Menge Markdown: Tool-Guides, README-Dateien, interne Spezifikationen und die Dokumente, die Sie gerade lesen Ein Inhaltsverzeichnis, das ich von Hand pflegen muss, ist ein Inhaltsverzeichnis, das irgendwann liegen wird Also habe ich das gebaut Markdown-TOC-Generator Langweiligen Teil jedes Mal richtig zu machen, und diese Anleitung ist alles, was ich über Ankerglieder beim Bau gelernt habe.
tl; dr: Ein Markdown-Inhaltsverzeichnis ist eine verschachtelte Liste von Links, die zu Überschriften auf derselben Seite springen Die Links funktionieren, weil jede Überschrift eine automatische Anker-ID erhält, und das slug, das GitHub zuweist, folgt einer bestimmten Regel: den Text klein schreiben, andere Interpunktionen als Bindestriche weglassen und Leerzeichen in Bindestriche umwandeln Fügen Sie Ihren Markdown in den Generator ein, wählen Sie aus, welche Überschriftenebenen Sie einbinden möchten, und kopieren Sie die Liste Das Tool berechnet die genauen slugsGitHub-Render, einschließlich der
-1Suffix für doppelte Überschriften, also geht beim Zurückfügen nichts kaputt.
Was ist ein Markdown Inhaltsverzeichnis?
Ein Inhaltsverzeichnis in Markdown ist keine spezielle Syntax. gebräuchliche Marke Definiert kein solches Konstrukt, und GitHub Flavored Markdown auch nicht Es ist eine gewöhnliche Liste, wo jedes Element ein Link ist, und jeder Link auf einen Anker innerhalb desselben Dokuments zeigt Wenn ein Markdown-Renderer wie GitHub eine Überschrift in HTML umwandelt, gibt er auch diese Überschrift an id Attribut. Eine Überschrift geschrieben als ## Getting Started Grob wird <h2 id="getting-started">Getting Started</h2>. Sobald diese ID existiert, wird ein Link geschrieben als [Getting Started](#getting-started) Scrollt die Seite dazu.
Ein Inhaltsverzeichnis ist also nur eine Sammlung dieser Links, die eingerückt sind, um die Überschriftenhierarchie widerzuspiegeln:
- [Getting Started](#getting-started)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
Der gesamte Trick lebt in einem Wort aus jenem Beispiel: dem Anker Holen Sie sich den Anker falsch und der Link fällt stillschweigend aus, scrollen Sie nirgendwo hin, Holen Sie es richtig und der Inhaltsblock funktioniert auf GitHub, in den meisten statischen Site-Generatoren, und in Dokumentationsplattformen, die der gleichen Konvention folgen Der harte Teil ist nicht das Schreiben der Liste Der harte Teil ist die Vorhersage der genauen ID, die jeder Renderer zuweisen wird, weshalb es ein verlorenes Spiel auf jedem Dokument ist, das sich ändert.
Wie werden Kursanker eigentlich erzeugt?
GitHub' s slug Algorithmus ist deterministisch und es lohnt sich, sich das Auswendig zu lernen, denn sobald Sie es wissen, können Sie jeden Anker auf der Seite vorhersagen Die Schritte lauten der Reihe nach: Konvertieren Sie den Überschriftstext in Kleinbuchstaben, entfernen Sie jedes Zeichen, das kein Buchstabe, keine Zahl, kein Leerzeichen oder kein Bindestrich ist, und ersetzen Sie dann jedes Leerzeichen durch einen Bindestrich Das ist die ganze Regel.
Die Folgen sind dort, wo Menschen hinfahren Betrachten Sie eine Überschrift wie ## Set Up & Config. Untergehäuse ergibt set up & config. Das Entfernen des Ampersands (aber das Verlassen der Räume um ihn herum) ergibt set up config Mit zwei Räumen, wo die & Früher war. Räume in Bindestriche zu verwandeln, ergibt set-up--configMit einem doppelten Bindestrich. Dieser doppelte Bindestrich sieht aus wie ein Fehler, aber er ist genau das, was GitHub rendert, also ist es genau das, was Ihr Link braucht Ein Tool, das " aufräumt" der doppelte Bindestrich würde einen Link erzeugen, der sich nicht auflöst.
Satzzeichenlastige Überschriften brechen weiter zusammen, als man erwartet. ## C++ Guide wird c-guide„, weil beide Pluszeichen entfernt werden und der verbleibende Raum zu einem einzigen Bindestrich wird. ## What's New? wird whats-new, weil Apostroph und Fragezeichen verschwinden Emoji und die meisten Symbole verschwinden ganz Die Markdown-TOC-Generator Wendet dieses Regelzeichen für Zeichen an, sodass das slug, das Ihnen zeigt, die ID ist, die GitHub erstellen wird, ohne dass ein Vermutungen erforderlich ist.
Was passiert, wenn zwei Überschriften gleich sind?
Dokumente wiederholen Überschriften Ein Changelog könnte drei Abschnitte haben, die alle betitelt sind ### Fixed. Wenn jeder von ihnen das slug produzieren würde fixedNur der erste Link würde funktionieren GitHub löst das durch Nummerierung der Duplikate: der erste Fixed Bekommt fixedDer zweite bekommt fixed-1Der Dritte bekommt fixed-2, und so weiter in Dokumentenreihenfolge Das Suffix wird nach der Basis slug mit einem Bindestrich angehängt.
Das ist einer der häufigsten Gründe, warum ein handgeschriebenes Inhaltsverzeichnis aus dem Takt gerät, man fügt einen zweiten Abschnitt mit einem bereits verwendeten Namen hinzu, der Anker wird leise -1, und Ihr alter Link zeigt jetzt an die falsche Stelle oder überhaupt nirgendwo. Der Generator verfolgt jedes slug, das er ausgegeben hat, und wendet dasselbe numerische Suffix an, sodass wiederholte Überschriften auf das richtige Vorkommen verweisen.
Welche Überschriften liest das Tool?
Markdown hat zwei Überschriftenstile, und ein kompletter Generator muss beide lesen Der gemeinsame ist ATX, wo eine Zeile mit eins bis sechs beginnt # Zeichen gefolgt vom Überschriftstext Die Anzahl der Hashes ist das Level, also # H1 ist und ###### H6 ist, ist der zweite Stil Setext, wo in der nächsten Zeile eine Textzeile mit Gleichheitszeichen für ein H1 oder Bindestrichen für ein H2 unterstrichen wird:
Document Title
==============
A Section
---------
Beide Stile erzeugen Überschriften mit Anker-IDs, beide gehören also in ein Inhaltsverzeichnis Der knifflige Teil mit Setext ist, eine echte unterstrichene Überschrift von einer horizontalen Regel abgesehen zu erzählen, denn eine Zeile Bindestriche kann entweder bedeuten Die Regel, die der Generator verwendet, ist, dass eine Bindestrichunterstreichung nur dann als Überschrift zählt, wenn die Zeile direkt darüber gewöhnlicher Absatztext ist, nicht eine leere Zeile, ein Listenelement, ein Blockquote oder ein anderes Blockkonstrukt A --- Allein mit Leerzeilen drumherum zu sitzen ist ein thematischer Bruch, und er wird korrekt ignoriert.
Es gibt noch eine Kategorie zu handhaben, und es ist die, die naive Werkzeuge stillschweigend ruiniert: Überschriften im Code Wenn Ihr Dokument einen eingezäunten Codeblock enthält, der Shell-Befehle anzeigt, beginnen einige dieser Zeilen mit # Als Kommentare Das sind keine Überschriften, und sie dürfen niemals im Inhalt erscheinen Der Generator verfolgt eingezäunte Codeblöcke (die durch dreifache Backticks oder dreifache Tilden abgegrenzten) und überspringt jegliche # Linie in ihnen Ein Shell-Kommentar wie # install dependencies In einem Beispiel bleibt, wo es hingehört, im Beispiel.
Wie kontrolliere ich die Tiefe des Inhaltsverzeichnisses?
Ein Inhaltsverzeichnis, das jede Überschrift bis hinunter zu H6 auflistet, ist kein Inhaltsverzeichnis, es ist eine zweite Kopie des Dokuments Die meisten READMEs lesen am besten, wenn der Inhalt nur H2 und H3 abdeckt, und geben den Lesern die Hauptabschnitte und ihre unmittelbaren Kinder, ohne sie im Detail zu ertränken Der Generator lässt Sie einen Mindest - und einen Höchstwert festlegen, und er umfasst nur die Überschriften, die in diesen Bereich fallen.
Das subtile Verhalten hier ist die Einrückung, wenn man H2 bis H4 mit einbezieht, ist die flachste Überschrift, die man beibehielt, ein H2, und sie sollte bündig am linken Rand sitzen und nicht eingedrückt, als ob ein unsichtbares H1 darüber wäre Der Generator misst die Verschachtelungstiefe relativ zur flachsten Überschrift, die er tatsächlich enthält, sodass ein Inhaltsblock, der bei H2 beginnt, ohne Gedankenstrich beginnt. Dies ist der Unterschied zwischen einer Liste, die absichtlich aussieht, und einer Liste, die aussieht, als hätte sie ihre erste Spalte verloren.
Sie können auch die Listenmarkierung auswählen Eine ungeordnete Liste verwendet für jeden Eintrag ein Aufzählungspunkt, das ist das herkömmliche Aussehen für eine README Eine geordnete Liste nummeriert die Einträge, und der Generator startet die Zählung innerhalb jeder Verschachtelungsebene neu, sodass eine nummerierte Gliederung richtig liest, anstatt direkt von eins bis fünfzig zu zählen Die Einrückung kann zwei Leerzeichen, vier Leerzeichen oder eine Registerkarte sein, je nachdem, was der Rest Ihres Dokuments verwendet.
Wie sieht es mit akzentuierten und nicht-lateinischen Überschriften aus?
Nicht jede Überschrift ist reines Englisch, und die slugRegel muss zurechtkommen GitHub behält Buchstaben von anderen Alphabeten, anstatt sie zu entfernen, also eine Überschrift wie ## Configuración Behält seine akzentuierten Charaktere und wird configuración‘und eine Überschrift in kyrillischer oder griechischer Sprache behält auch diese Buchstaben. Was entfernt wird, sind Satzzeichen und Symbole, keine Buchstaben, unabhängig vom Skript. Der Generator folgt dem gleichen Prinzip, indem er jeden Unicode-Buchstaben oder jede Unicode-Ziffer als gültiges slugZeichen behandelt, sodass ein mehrsprachiges Dokument Anker erzeugt, die mit dem übereinstimmen, was GitHub rendert, und nicht eine Reihe leerer Links.
Das ist wichtiger, als es zuerst erscheint Teams, die Dokumentationen auf Spanisch, Deutsch oder Japanisch schreiben, stellen oft fest, dass naive slug ihre Überschriften in unbrauchbare Anker verstümmeln, denn diese Tools gehen von ASCII aus Wenn Ihre Links jemals auf nichts auf ein übersetztes README gezeigt haben, ist ein slug, das die Nicht-ASCII-Buchstaben stillschweigend verworfen hat, mit ziemlicher Sicherheit der Grund dafür. Wenn Sie den Inhaltsblock mit einem Unicode-fähigen Tool generieren, wird diese gesamte Klasse defekter Links entfernt, und es bedeutet, dass dasselbe Dokument Überschriften in mehr als einer Sprache halten kann, ohne dass einer von ihnen seine Anker verliert.
Wann sollte ich einen generierten TOC gegenüber einem automatischen verwenden?
Einige Plattformen erstellen für Sie ein Inhaltsverzeichnis GitLab unterstützt eine [[_TOC_]] Token, einige Wikis injizieren automatisch eine Inhaltsbox, und Dokumentationsframeworks wie Docusaurus rendern eine Onpage-Umrisslinie aus Ihren Überschriften, ohne dass Sie etwas schreiben Wenn Sie innerhalb eines dieser Systeme arbeiten, verwenden Sie die integrierte Funktion Sie bleibt mit Null Aufwand aktuell, da die Plattform es auf jedem Render regeneriert.
Der Generator verdient seinen Platz überall sonst, und & quot; überall sonst" ist ein großer Ort GitHub READMEs erzeugen keinen Inhaltsblock automatisch, so dass eine Repository-Landingpage eine echte Markdown-Liste benötigt, die in die Datei festgelegt wird Markdown, der in etwas anderes umgewandelt, per E-Mail gesendet, in ein Problem eingefügt oder von einem minimalen Betrachter gerendert wird, benötigt einen statischen Inhaltsblock, da es keine Engine gibt, um einen solchen auf der Fliege aufzubauen Die folgende Tabelle legt fest, wo jeder Ansatz passt.
| Situation | Bester Ansatz | wieso |
|---|---|---|
| GitHub README | Generierte statische Liste | GitHub rendert Überschriften-IDs, fügt jedoch keinen TOC automatisch ein |
| GitLab-Wiki oder Dokumente | [[_TOC_]] Token |
Nativ, immer aktuell |
| Docusaurus / MkDocs-Seite | Eingebauter Umriss | Framework rendert es aus Überschriften |
| Einfache Markdown-Datei für den Export | Generierte statische Liste | Kein Renderer, der zur Ansichtszeit einen baut |
| Beschreibung der Anfrage ausgeben oder ziehen | Generierte statische Liste | Anker funktionieren, aber nichts generiert die Liste automatisch |
Die Faustregel: wenn das Ding, das Ihren Markdown anzeigt, den Inhalt selbst erstellen kann, lassen Sie es Wenn Ihr Markdown irgendwo gelesen werden könnte, wo dies nicht möglich ist, generieren Sie die Liste und binden Sie sie ein Wenn Sie zwischen Formaten konvertieren, wird die Markdown in HTML-Konverter und das HTML-zu-Markdown-Konverter Pair auf natürliche Weise mit einem generierten Inhaltsblock, da die Anker die Hin- und Rückfahrt überstehen.
Wie passt das zum Rest eines Markdown-Workflows?
Ein Inhaltsverzeichnis ist ein Stück, um lange Dokumente lesbar zu halten, und es funktioniert am besten neben ein paar Gewohnheiten Halten Sie Ihren Überschriftstext stabil, sobald Sie Links dazu veröffentlicht haben, denn durch Umbenennen einer Überschrift ändert sich ihr slug und bricht jeden Link, der darauf hingewiesen hat Wenn Sie den Inhalt umbenennen, regenerieren Sie den Inhalt, anstatt den einen Link zu bearbeiten, an den Sie sich erinnern, da bei einem Umbenennen die Nummerierung von Duplicate-Suffixen oft weiter unten in der Datei verschoben wird.
Strukturierte Inhalte profitieren von anderen Tools derselben Familie Wenn sich ein Dokument auf tabellarische Daten stützt, kann die Markdown-Tabellengenerator Richtig ausgerichtete Pipe-Tabellen erstellt, die eine handgetippte Tabelle fast nie richtig bekommt Wenn Sie chaotisches HTML erben, das sauber werden muss Markdown, oder sauber Markdown, das HTML werden muss, übernehmen die Konverter die Übersetzung unter Beibehaltung der Überschriftenstruktur Und wenn Sie ein Dokument auf Länge oder Keyword-Balance prüfen, wird die Wortzähler Gibt Ihnen die Zahlen, ohne Ihren Entwurf in etwas Cloud-basiertes einzufügen.
Alles läuft im Browser, was mehr zählt, als es klingt Ein README enthält oft unveröffentlichte Feature-Namen, interne URLs oder Client-Details, und all das sollte nicht auf einen Server eines Drittanbieters hochgeladen werden, nur um eine Liste von Links zu erstellen Der Generator analysiert Ihren Markdown mit clientseitigem JavaScript, sodass das Dokument Ihre Maschine nie verlässt Wenn Sie über Privatsphäre im Entwickler-Tooling nachdenken, ist das Schreiben darauf Datenschutz und Online-Tools Deckt ab, warum die lokale Verarbeitung die richtige Voreinstellung ist, und die Webentwickler-Toolkit Rundet den Rest der Dienstprogramme auf, für die ich täglich erreichbar bin.
Ein schnell gearbeitetes Beispiel
Angenommen, Sie haben dieses Dokument:
# Payment Service
## Getting Started
### Requirements
### Local Setup
## API Reference
### Authentication
### Errors
## Deployment
Stellen Sie den Bereich auf H2 bis H3 ein, wählen Sie eine Liste mit Aufzählungszeichen und lassen Sie Ankerverbindungen auf. Der Generator erzeugt:
- [Getting Started](#getting-started)
- [Requirements](#requirements)
- [Local Setup](#local-setup)
- [API Reference](#api-reference)
- [Authentication](#authentication)
- [Errors](#errors)
- [Deployment](#deployment)
Der H1-Titel ist ausgeschlossen, weil er über dem Bereich liegt, die H2-Abschnitte bündig links liegen und ihre H3-Kinder eine Ebene eingerückt sind. Fügen Sie diesen Block direkt unter dem Titel in Ihr README ein und jeder Eintrag springt zu seinem Abschnitt auf GitHub. Das ist die ganze Arbeit, erledigt in der Zeit, die zum Lesen dieses Satzes benötigt wird, und sie bleibt korrekt, weil eine Maschine anstelle von Ihnen das slugs berechnet hat.
Häufig gestellte Fragen
Wie funktioniert ein Markdown Inhaltsverzeichnis?
Ein Markdown-Inhaltsverzeichnis ist eine Liste von Links, die auf Überschriftenanker innerhalb derselben Seite verweisen Jede Überschrift in einem Markdown-Dokument erhält eine automatische ID und ein Link, der als geschrieben wird Abschnitt Springt dazu Dieses Tool liest Ihre Überschriften, baut die passenden Anker auf, und stellt die verschachtelte Liste für Sie zusammen.
Wie werden die Ankerlinks generiert?
Anker folgen der GitHub slug-Regel: Der Überschriftstext ist klein geschrieben, andere Interpunktionen als Bindestriche werden entfernt und Leerzeichen werden zu Bindestrichen. " Set Up & amp; Config" wird zum id-Setup-Config. Wenn zwei Überschriften dasselbe slug erzeugen, erhält die zweite ein -1-Suffix, die dritte -2 usw. und passt sich an, wie GitHub sie rendert.
Funktioniert es mit GitHub README-Dateien?
Ja. Der slug-Algorithmus spiegelt den Algorithmus wider, den GitHub zum Rendern von Überschriften-IDs verwendet, sodass die Inhaltsverzeichnislinks innerhalb eines README auf github.com korrekt aufgelöst werden. Fügen Sie Ihr README ein, wählen Sie Ihre Überschriftenebenen aus und legen Sie die generierte Liste unter den Titel.
Kann ich auswählen, welche Überschriftenebenen erscheinen?
Ja. Legen Sie einen Mindest - und Höchststand fest, zum Beispiel H2 bis H4, und nur Überschriften in diesem Bereich sind enthalten Die Nisttiefe wird relativ zum flachsten enthaltenen Überschrift gemessen, so dass die Umrisslinie nie mit einem großen leeren Einrücker beginnt.
Sind Überschriften innerhalb von Codeblöcken enthalten?
Nr. Zeilen, die mit # innerhalb eines eingezäunten Codeblocks beginnen (durch dreifache Backticks oder dreifache Tilden begrenzt), werden als Code und nicht als Überschriften behandelt, sodass Beispielausschnitte und Shell-Kommentare nie im Inhaltsverzeichnis erscheinen.
Was ist der Unterschied zwischen einem bestellten und einem ungeordneten TOC?
Ein ungeordnetes Inhaltsverzeichnis verwendet für jeden Eintrag Aufzählungszeichen wie einen Bindestrich, während ein geordnetes Zahlen verwendet, die innerhalb jeder Verschachtelungsebene inkrementieren Wählen Sie geordnet, wenn die Leser von einer nummerierten Gliederung profitieren, und ungeordnet für einen leichteren, konventionelleren Inhaltsblock.
Unterstützt das Tool Setext-Überschriften?
Ja. Es liest sowohl ATX-Überschriften, die mit # - als auch mit Setext-Überschriften beginnen, wobei eine Textzeile mit Gleichheitszeichen für H1 oder Bindestrichen für H2 unterstrichen ist Beide Stile werden auf die gleiche Weise in Anker-Links umgewandelt.
Ist der Markdown TOC Generator frei und privat?
Ja. Es ist völlig kostenlos ohne Anmeldung und ohne Einschränkungen. Das gesamte Parsen erfolgt in Ihrem Browser mit clientseitigem JavaScript, sodass der Markdown, den Sie einfügen, Ihr Gerät nie verlässt und das Tool nach dem Laden der Seite offline weiterarbeitet.
