Markdown-Inhaltsverzeichnis automatisch generieren: Navigation für Ihre Docs

Jeder Entwickler kennt das: Man schreibt eine lange README-Datei oder Dokumentation und bemerkt dann — irgendwo in der Mitte — dass man ein Inhaltsverzeichnis braucht. Also verbringt man zwanzig Minuten damit, es manuell zu erstellen, achtet peinlich genau auf Kleinschreibung, ersetzt Leerzeichen durch Bindestriche, entfernt Sonderzeichen. Dann ändern sich Überschriften und die Hälfte der Links ist kaputt.

Es ist eines dieser kleinen, aber wirklich nervigen Probleme, das eine vollständig mechanische Lösung hat. Der Algorithmus zur Anker-ID-Generierung für GitHub-Flavored Markdown ist deterministisch und gut dokumentiert. Es gibt keinen Grund, das manuell zu tun.

Der Markdown-Inhaltsverzeichnis-Generator automatisiert den gesamten Prozess. Markdown einfügen, korrekt eingerücktes und verlinktes Inhaltsverzeichnis erhalten, direkt wieder ins Dokument einfügen — fertig.

Warum Inhaltsverzeichnisse wichtiger sind, als man denkt

Ein Inhaltsverzeichnis ist nicht dekorativ. Bei längeren Dokumenten — alles über tausend Wörter — hat es eine echte Navigationsfunktion. Leser überfliegen das Inhaltsverzeichnis zuerst, um zu verstehen, was ein Dokument abdeckt, und springen dann direkt zum relevanten Abschnitt. Ohne eines scrollen sie entweder manuell oder geben auf.

Bei README-Dateien auf GitHub ist das besonders deutlich. Wenn ein Entwickler zum ersten Mal ein Repository besucht, das er evaluiert, überfliegt er die README. Wenn die README lang ist und kein Inhaltsverzeichnis hat, ist das mentale Modell des Projekts schwerer zu erfassen. Ein klares Inhaltsverzeichnis kommuniziert die Struktur sofort.

Wie der Anker-Algorithmus funktioniert

GitHub generiert Anker-IDs aus Überschriftentext nach einem einfachen Prozess:

1. Alle HTML-Tags entfernen
2. Den gesamten String in Kleinbuchstaben umwandeln
3. Alle Satzzeichen außer Bindestrichen und Leerzeichen entfernen
4. Leerzeichen durch Bindestriche ersetzen
5. Deduplizierung: Wenn ein Überschriftentext mehrfach vorkommt, wird -1, -2 etc. angehängt

## Erste Schritte wird also zu #erste-schritte. ## API-Referenz (v2) wird zu #api-referenz-v2.

Unterschied zwischen GitHub und GitLab

GitHub und GitLab folgen demselben Grundalgorithmus, unterscheiden sich aber leicht bei bestimmten Zeichen. Für die meisten deutschen Dokumentationen mit Umlauten gilt: GitHub und moderne Markdown-Renderer bewahren Unicode-Zeichen in Anker-IDs. ## Häufige Fragen wird zu #häufige-fragen. Das funktioniert, auch wenn die URL seltsam aussieht.

Der praktische Rat, wenn Sie für beide Plattformen schreiben: Halten Sie Überschriftentexte so einfach wie möglich — einfache Wörter, minimale Satzzeichen.

Praktisches Beispiel

Nehmen wir eine typische README-Struktur:

# Meine Bibliothek

## Installation

### macOS

### Linux

## Schnellstart

## API-Referenz

### Konfigurationsoptionen

### Methoden

## Mitwirken

## Lizenz

Der Generator produziert folgendes Inhaltsverzeichnis:

## Inhaltsverzeichnis

- [Installation](#installation)
  - [macOS](#macos)
  - [Linux](#linux)
- [Schnellstart](#schnellstart)
- [API-Referenz](#api-referenz)
  - [Konfigurationsoptionen](#konfigurationsoptionen)
  - [Methoden](#methoden)
- [Mitwirken](#mitwirken)
- [Lizenz](#lizenz)

Wichtig: # Meine Bibliothek als H1-Überschrift wird aus dem Inhaltsverzeichnis ausgeschlossen. H1 ist der Dokumenttitel, kein Navigationsziel. Die Hierarchie wird korrekt abgebildet — H2 auf der obersten Ebene, H3 eingerückt.

Sonderzeichen und Grenzfälle

Ehrlichkeit ist hier angebracht, weil einige Situationen Aufmerksamkeit erfordern.

Emoji in Überschriften — Beliebt in GitHub-Projekten: ## 🚀 Erste Schritte. Das Ankerverhalten variiert je nach Renderer. Wenn Ihre Überschriften Emoji enthalten, überprüfen Sie die generierten Ankerlinks direkt auf der Zielplattform.

Code-Spans in Überschriften — ## Die `render()`-Funktion — die Backticks werden entfernt, was #die-render-funktion ergibt. Das ist meist das gewünschte Ergebnis.

Klammern und Sonderzeichen — ## API-Referenz (v2) — Klammern werden entfernt, ergibt #api-referenz-v2. Wenn mehrere Abschnitte ähnliche Namen haben, kann der Anker unerwartet aussehen.

Integration in den Workflow

Der typische Arbeitsablauf ist einfach:

1. Schreiben Sie das Dokument zuerst, ohne sich um das Inhaltsverzeichnis zu sorgen
2. Wenn die Struktur sich gefestigt hat, fügen Sie das Markdown in den Inhaltsverzeichnis-Generator ein
3. Kopieren Sie das generierte Inhaltsverzeichnis
4. Fügen Sie es am Anfang des Dokuments ein, nach dem Einführungsabsatz

Synchronisierung aufrechterhalten

Die Haupteinschränkung ist, dass der Generator das Inhaltsverzeichnis nicht automatisch aktualisiert, wenn Sie das Dokument ändern. Bei Überschriftenänderungen müssen Sie es neu generieren und ersetzen.

Für kleine Dokumente ist das kein Problem. Für häufig aktualisierte Dokumentationsprojekte gibt es Automatisierungsoptionen:

• doctoc (npm-Paket): Aktualisiert das Inhaltsverzeichnis direkt im Dokument, ideal als pre-commit-Hook
• VS Code-Erweiterungen: Mehrere Erweiterungen aktualisieren Inhaltsverzeichnisse beim Speichern automatisch
• GitHub Actions: Workflow konfigurierbar, der doctoc bei jedem Push ausführt

Ergänzende Tools

Wenn Sie viel mit Markdown arbeiten, sind folgende Tools auf dieser Website nützlich:

Das Markdown-Vorschau-Tool rendert jedes Markdown-Dokument in Echtzeit, sodass Sie visuell bestätigen können, wie Überschriften und Inhaltsverzeichnis aussehen werden. Gut zum Erkennen von Formatierungsproblemen.

Der Markdown-zu-HTML-Konverter ist nützlich, wenn Sie die eigentliche HTML-Ausgabe benötigen — etwa für ein CMS oder eine E-Mail-Vorlage.

Der Markdown-Tabellengenerator erstellt die Pipe-getrennte Tabellensyntax, die manuell ausgesprochen mühsam zu schreiben ist.

Tipps aus der Praxis

Beginnen Sie mit einer sauberen Überschriftenhierarchie. Wenn Ihr Dokument H2 und H3 ohne klare Struktur vermischt, spiegelt das generierte Inhaltsverzeichnis diese Verwirrung wider. Der Generierungsprozess deckt oft Strukturprobleme auf, die vorher unsichtbar waren.

Flache Strukturen sind in Ordnung. Ein Dokument mit nur H2-Überschriften produziert ein einfaches, nicht verschachteltes Inhaltsverzeichnis — das ist oft genau richtig. Fügen Sie keine H3-Unterüberschriften hinzu, nur damit das Inhaltsverzeichnis aufwendiger wirkt.

Bedenken Sie das Lesemuster Ihrer Zielgruppe. Für API-Referenzdokumentationen, die Entwickler häufig durchsuchen, ist ein umfassendes Inhaltsverzeichnis mit vollständiger Verschachtelung hilfreich. Für eine README, die Erstbenutzer einmal von oben bis unten lesen, ist oft ein kürzeres Inhaltsverzeichnis mit nur den Hauptabschnitten ausreichend.

Gute Dokumentation zu schreiben ist eine Fähigkeit. Die mechanischen Teile zu automatisieren — Anker-ID-Generierung, Link-Formatierung, Einrückung — ermöglicht es, sich auf den eigentlichen Inhalt zu konzentrieren.

Probieren Sie den Markdown-Inhaltsverzeichnis-Generator bei Ihrer nächsten README oder Dokumentationsdatei aus.