Inhaltsverzeichnis: Format und Regeln

In der Elementbibliothek teilen ein kurzer Überblick und ein Inhaltsverzeichnis den Lesern mit, was eine Seite abdeckt, bei welchen Entscheidungen sie hilft und wie sie zu dem benötigten Abschnitt springen können.

Kurzer Überblick. Verwenden Sie dieses gepaarte Eröffnungselement auf langen oder strukturell komplexen Seiten. Schreiben Sie einen 40–90 Wörter umfassenden Überblick, der Umfang und erwartetes Ergebnis festlegt, und erstellen Sie dann eine Inhaltsliste aus stabilen H2-Überschriften und nur nützlichen H3-Überschriften. Auf dieser Seite bleibt das Live-Inhaltssteuerelement unten versteckt, bis der Leser mehr als 300 Pixel gescrollt hat; es erscheint dann als festes Desktop-Dropdown unterhalb der Site-Header.

Warum dieses Element wichtig ist

Leser beginnen nicht jede lange Seite an derselben Stelle. Eine Person benötigt eine Definition, eine andere möchte Implementierungsschritte sehen, und eine dritte überprüft eine einzelne Einschränkung, bevor sie eine Arbeit genehmigt. Ein kurzer Überblick beantwortet die Frage „Bin ich hier richtig?“, bevor der Leser Aufmerksamkeit investiert. Die Inhaltsliste beantwortet „Wo ist der Teil, den ich brauche?“, ohne einen linearen Durchlese zu erzwingen.

Die beiden Teile werden gemeinsam spezifiziert, weil sie benachbarte, aber unterschiedliche Orientierungsprobleme lösen. Der Überblick erklärt das Versprechen der Seite, ihre Grenzen und das nützliche Ergebnis in Sätzen. Die Inhaltsliste legt den Weg durch dieses Versprechen als Ziele offen. Eine Inhaltsliste ohne Überblick kann zeigen, dass eine Seite Abschnitte namens „Konfiguration“ und „Barrierefreiheit“ hat, aber nicht erklären, ob die Seite eine konzeptionelle Einführung oder eine Produktionsspezifikation ist. Ein Überblick ohne Navigation kann den Umfang festlegen, aber den Leser dennoch durch 3.000 Wörter jagen lassen.

Dieses Element verbessert auch die maschinelle Extrahierbarkeit, d. h. die Fähigkeit von Software, eine Passage zu isolieren und ihren Zweck außerhalb der gesamten Seite zu bewahren. Der Überblick ist nach Titel und Beschreibung eine zweite prägnante, in sich geschlossene Zusammenfassung. Das Quell-Inhaltsverzeichnis von Hugo ist eine verlinkte, maschinenlesbare Gliederung der Seitenabdeckung und -hierarchie; der aktuelle sticky Renderer wandelt diese Links in Optionen um, die ihre URL-Fragmentwerte, den #section-Teil einer URL, beibehalten. Suchsysteme, Abrufwerkzeuge, Browsererweiterungen und KI-Agenten können die Dokumentgliederung nutzen, um wahrscheinliche Antwortbereiche zu identifizieren, bevor sie jeden Absatz verarbeiten. Dies garantiert keine Suchfunktion oder KI-Zitierung; es reduziert Mehrdeutigkeiten darüber, wo Themen beginnen und wie sie zusammenhängen.

Die Paarung darf keine Wiederholung erzeugen. Ein Überblick gibt Umfang und Ergebnis an. Ein direkter Antwortblock beantwortet die primäre Frage. Die wichtigen Erkenntnisse nennen Schlussfolgerungen, die es wert sind, behalten zu werden. Wenn alle drei in verschiedenen Boxen dasselbe sagen, wird die Eröffnung eher zum Hindernis als zur Hilfe.

Verwendung

Die Inhaltsliste verdient ihren Platz, wenn Springen ein wahrscheinliches Leserverhalten ist. Die Wortanzahl ist ein nützlicher Näherungswert, aber die Struktur ist der entscheidende Faktor.

Verwenden Sie den Überblick allein, wenn der Titel weit interpretiert werden könnte, wenn die Seite bewusst angrenzende Themen ausschließt oder wenn der Leser das erwartete Ergebnis kennen muss, bevor er fortfährt. Eine 900-Wörter-Richtlinienseite benötigt möglicherweise einen Zwei-Sätze-Überblick, auch wenn sie keine Navigation benötigt.

Verwenden Sie die Inhaltsliste nur dann allein, wenn Titel und Eröffnung den Umfang bereits unmissverständlich machen. Diese Beinahe-Ausnahme ist bei Referenzseiten üblich: Die Eröffnung kann eine direkte Definition enthalten, die die Orientierungsaufgabe übernimmt, während eine lange Reihe unabhängiger Felder dennoch Navigation benötigt.

Verwenden Sie keinen der beiden Teile als Dekoration. Ein TOC mit sechs Einträgen in einem 700-Wörter-Artikel fügt eine zusätzliche Entscheidung vor der Antwort hinzu. Ein Überblick, der sagt „Dieser Leitfaden erkundet alles, was Sie wissen müssen“, definiert weder Umfang, Ergebnis noch Ausschlüsse. Verwenden Sie das Paar nicht, um eine schwache Überschriftenstruktur zu verbergen: Wenn Überschriften sich überschneiden, inkonsistente Grammatik verwenden oder eine Idee in viele winzige Abschnitte aufteilen, beheben Sie das Dokument, bevor Sie seine Gliederung offenlegen.

Positionierung

Die Position ist Teil der Bedeutung des Elements. Der Überblick muss nach dem Hero-Bereich oder der direkten Eröffnungsantwort und vor der ersten H2 erscheinen. Er kann ein kurzer Absatz oder eine kompakte Liste sein, muss aber gelesen werden, bevor der Leser sich auf den Hauptteil einlässt. Der TOC-Aufruf gehört unmittelbar nach den Überblick, damit die erstellte Quelle Orientierung und Navigation zusammenhält, auch wenn das sticky Steuerelement dieser Site erst nach einem Scrollen von 300 Pixeln sichtbar wird.

Das Paar darf keine Definition unterbrechen, eine Behauptung von ihrem Beleg trennen oder zum ersten Mal mitten im Dokument erscheinen. Platzieren Sie es nicht zwischen einer Überschrift und deren einleitendem Absatz: Die Beziehung zwischen Überschrift und Erklärung sollte direkt bleiben. Platzieren Sie keine andere Überblick-Komponente direkt daneben. Wenn ein direkter Antwortblock oder ein Block mit wichtigen Erkenntnissen erforderlich ist, weisen Sie unterschiedliche Aufgaben zu und verwenden Sie diese Reihenfolge: direkte Antwort, kurzer Umfangsüberblick, TOC-Aufruf, erster Hauptabschnitt. Lassen Sie eine der Zusammenfassungen weg, wenn die Formulierungen sich dennoch überschneiden.

Verwenden Sie den Shortcode einmal pro Seite. Seine gerenderten IDs (tocDropdown, tocSelect, selectTrigger und zugehörige Steuerelemente) sind festgelegt, sodass eine zweite Instanz doppelte Dokument-IDs und unvorhersehbare Skripte erzeugt.

Anatomie

Das Element hat sechs bedeutungsvolle Bereiche. Die ersten fünf sind Inhalt oder Verhalten; der Fortschrittsanzeiger ist ein Status. Die Legende wird in der Seite belassen, damit sie lesbar bleibt, wenn der Screenshot in der Größe verändert oder ersetzt wird.

1. Überblickstext: 40–90 Wörter, die Umfang, beabsichtigtes Ergebnis und wichtige Grenzen angeben.
2. Sticky Wrapper-Titel: standardmäßig der Seitentitel oder das erstellte title-Attribut, wenn ein kürzeres Label klarer ist.
3. Aktueller-Abschnitt-Beschriftung: beginnt mit „Abschnitt auswählen…“ und ändert sich, wenn der IntersectionObserver des Browsers, eine API, die erkennt, wenn Elemente in einen definierten Viewport-Bereich eintreten, Abschnitte als aktiv markiert.
4. Dropdown-Auslöser: öffnet bei Klick die generierte Liste der Abschnittsziele in der aktuellen Implementierung.
5. Überschriftenoptionen: Links, die aus dem Seiten-Inhaltsverzeichnis von Hugo abgeleitet werden, derzeit H2 und H3 aufgrund von markup.toml.
6. Fortschrittsbalken: zeigt den Anteil des gesamten scrollbaren Dokuments an, der durchlaufen wurde; er kennzeichnet nicht den Abschluss eines Abschnitts.

Gestaltungsbeispiele

Die Galerie zeigt Verhaltenszustände und nicht dekorative Designs. Der zugrundeliegende Inhalt bleibt gleich, damit Prüfer Timing, Hierarchie, Beschneidung und Interaktion vergleichen können.

Es werden keine alternativen visuellen Varianten über Markdown erstellt. title ändert das Label und class fügt Wrapper-Klassen hinzu, aber keines erzeugt ein semantisch anderes Element. Neue Farb-, Karten-, Seitenleisten- oder Inline-Listen-Ausführungen erfordern eine Komponentenentscheidung und keine willkürliche Klasse, die im Inhalt hinzugefügt wird.

Parameter

Der Überblick und der TOC teilen einen redaktionellen Vertrag, aber nur der sticky TOC wird vom aktuellen Shortcode gerendert. Konfigurationswerte sind enthalten, weil sie die Ausgabe ändern, auch wenn Autoren sie nicht pro Aufruf festlegen können.

Die Abhängigkeit ist leicht zu übersehen: Eine Seite ohne H2-Überschriften rendert stillschweigend keinen sticky TOC, da Hugo keine verwendbare Gliederung erzeugt und das Partial nur dann Markup ausgibt, wenn es Überschriften gibt. Mit der aktuellen Konfiguration sind H2 und deren H3-Abkömmlinge berechtigt; H4 und tiefere Überschriften sind ausgeschlossen. Das Partial parst normalerweise Hugos .TableOfContents. Sein HTML-Fallback scannt nur gerenderte H2-Elemente, daher dürfen sich Autoren nicht auf das Fallback-Verhalten verlassen, um die H3-Navigation zu erhalten.

Syntax und Codebeispiele

Die portable Notation behält den Überblick als Elementkörper und die Navigationseinstellungen als Attribute. Überschriftenlinks werden weiterhin aus dem umgebenden Dokument generiert und nicht vom Autor dupliziert.

:::quick-overview-and-toc{title="Auf dieser Seite" class=""}
Dieser Leitfaden erklärt, wann das Element verwendet werden sollte, wie das sticky Hugo-Steuerelement funktioniert,
und wie zugängliche, stabile Abschnittsziele nach der Veröffentlichung erhalten bleiben.
:::

Die aktuelle Hugo-Abbildung schreibt den Überblick als normales Markdown und ruft den ausgelieferten Shortcode einmal auf. Es gibt keinen JSON-Körper.

Dieser Leitfaden erklärt, wann das Element verwendet werden sollte, wie das sticky Hugo-Steuerelement funktioniert,
und wie zugängliche, stabile Abschnittsziele nach der Veröffentlichung erhalten bleiben.

{{< table-of-contents title="Auf dieser Seite" class="" >}}

Die WordPress-Block-Abbildung speichert denselben Körper und dieselben Attribute. Eine Site, die den Block nicht registriert hat, kann die äquivalente Shortcode-Form verwenden; sie darf die Überschriftenlinks nicht von Hand erstellen.

<!-- wp:amicited/quick-overview-and-toc {"title":"Auf dieser Seite","className":""} -->
<p>Dieser Leitfaden erklärt, wann das Element verwendet werden sollte, wie das sticky Steuerelement funktioniert,
und wie zugängliche, stabile Abschnittsziele nach der Veröffentlichung erhalten bleiben.</p>
<!-- /wp:amicited/quick-overview-and-toc -->

[amicited_quick_overview_toc title="Auf dieser Seite" class=""]
Dieser Leitfaden erklärt den Umfang, das Verhalten und die Ankerrichtlinie des Elements.
[/amicited_quick_overview_toc]

In allen drei Systemen ist die Quelle der Wahrheit die tatsächliche Überschriftenhierarchie des Dokuments. Eine manuell gepflegte Liste wird mit der Zeit von den Überschriften abweichen und auf IDs verweisen können, die nicht mehr vorhanden sind.

Beispiele

Gutes Beispiel

Kurzer Überblick. Dieser Leitfaden zeigt Content-Teams, wie sie eine Vergleichsseite planen, schreiben, überprüfen und pflegen. Er behandelt Belegstandards, Vergleichskriterien, Produktbehauptungen, zugängliche Tabellen und Nachveröffentlichungsprüfungen. Er behandelt keine bezahlte Platzierung oder Provisionsbedingungen von Affiliates.

Auf dieser Seite: Entscheidung definieren · Vergleichskriterien auswählen · Belege sammeln · Seite entwerfen · Behauptungen prüfen · Messen und pflegen

Dies funktioniert, weil der Überblick die Zielgruppe, das Ergebnis, die Abdeckung und die Grenze in 48 Wörtern nennt. Die sechs Ziele sind unterschiedliche Aufgaben, die ein Leser unabhängig voneinander wieder aufsuchen könnte. Ihre Bezeichnungen verwenden parallele Verbphrasen, sodass sowohl Menschen als auch Maschinen einen Prozess ableiten können. Keiner der Einträge wiederholt den Seitentitel oder legt einen trivialen Unterabschnitt offen.

Schlechtes Beispiel

Überblick: Willkommen zu unserem vollständigen Leitfaden. In der sich ständig verändernden Welt von heute gibt es viel zu wissen, also lesen Sie weiter, um alles zu erfahren.

Inhalt: Einleitung · Weitere Informationen · Wichtige Dinge · Andere Dinge · Fazit

Dies scheitert aus zwei Gründen. Der Überblick verwendet 22 Wörter, ohne Umfang, Leser, Ergebnis oder Ausschluss zu definieren. Die Einträge bezeichnen rhetorische Behälter statt Themen, sodass sie einem Leser nicht helfen, vorherzusagen, wo eine Antwort zu finden ist. Das Hinzufügen weiterer Überschriften würde es nicht beheben; das Dokument benötigt zuerst sinnvolle Abschnittsgrenzen.

Eine zweite Beinahe-Ausnahme ist eine 600-Wörter-Antwort mit „Überblick“, „Hintergrund“, „Details“, „Tipps“ und „Fazit“ in ihrem TOC. Selbst wenn jeder Anker funktioniert, fügt die Liste mehr Oberfläche als Navigationswert hinzu. Behalten Sie die direkte Eröffnung bei und entfernen Sie den TOC.

Schema-Markup und Barrierefreiheit

Hier bezeichnet Schema-Markup standardisierten maschinenlesbaren Code, der Entitäten und Eigenschaften identifiziert. Dieses Element hat keinen eigenen Typ oder Eigenschaft im Schema.org-Vokabular, und der Hugo-Shortcode gibt kein JSON-LD aus, die skriptbasierte Notation, die üblicherweise zur Veröffentlichung dieses Vokabulars verwendet wird. Markieren Sie den TOC nicht als ItemList, nur weil er eine Liste ist; das würde eher eine Liste von Themen als Navigation suggerieren. Der Überblick kann in die description einer Seite einfließen, wenn die Formulierung unabhängig geeignet ist, wird aber nicht automatisch in strukturierte Daten kopiert.

HTML- und ARIA-Verhalten sind hier wichtiger. ARIA, der Standard für zugängliche Internetanwendungen, stellt Rollen, Namen und Zustände bereit, wenn natives HTML dies nicht tut. Ein Landmarke ist ein benannter Seitenbereich, zu dem Benutzer von Assistenztechnologien springen können. Der Fokus ist das aktuelle Tastatur-Interaktionsziel.

Dies sind Implementierungstatsachen, keine Erlaubnis, Barrierefreiheit zu ignorieren. Inhaltsprüfer können heute Überschriftenklarheit, eindeutige IDs und logische Reihenfolge überprüfen. Komponentenverantwortliche müssen Auslöser-, Landmarken-, Fokus-, URL- und Bewegungsverhalten lösen, bevor sie die sticky Variante als tastaturzugänglich beschreiben.

Schreibregeln

Schreiben Sie den Überblick, nachdem die Seitenstruktur stabil ist. Dies verhindert, dass ein frühes Versprechen von der endgültigen Abdeckung abweicht. Halten Sie ihn zwischen 40 und 90 Wörtern. Bevorzugen Sie zwei oder drei Sätze; verwenden Sie drei bis fünf Aufzählungspunkte nur, wenn die Seite mehrere wirklich parallele Ergebnisse enthält. Geben Sie an, wobei die Seite dem Leser hilft, etwas zu verstehen, zu entscheiden oder zu tun. Nennen Sie einen Ausschluss, wenn der Titel vernünftigerweise mehr versprechen könnte, als die Seite liefert.

Verwenden Sie H2 für die wichtigsten Fragen, Phasen oder Entscheidungsbereiche der Seite. Beziehen Sie H3 nur dann in die Navigation ein, wenn es ein nützliches unabhängiges Ziel unter einer substanziellen H2 ist. Auf dieser Website umfasst die Konfiguration automatisch jede H2 und H3, daher ist die praktische Richtlinie strenger: Erstellen Sie keine Überschrift, es sei denn, sie verdient es, in der Navigation zu erscheinen. Streben Sie 5–18 Einträge insgesamt an. Wenn die generierte Liste 18 überschreitet, kombinieren Sie überlappende Abschnitte, entfernen Sie unnötige H3-Überschriften oder teilen Sie die Seite. Überspringen Sie niemals direkt von H2 zu H4, um eine Überschrift vor dem TOC zu verstecken; Überschriftenebenen drücken Hierarchie aus, nicht Styling oder Navigationspräferenz.

Verwenden Sie prägnante, beschreibende Überschriftentexte. Ein Leser sollte jedes Ziel verstehen, ohne den übergeordneten Absatz zu lesen. Bevorzugen Sie parallele Formen innerhalb einer Sequenz: „Kriterien wählen“, „Belege sammeln“ und „Behauptungen prüfen“ sind leichter zu überfliegen als eine Mischung aus Nomen, Fragen und vagen Bezeichnungen. Setzen Sie keine Zitate, werbliche Behauptungen, Emojis, Statusabzeichen oder vollständige Sätze in eine Überschrift, nur um den TOC zu beeinflussen.

Der Überblick darf niemals eine zweite Mini-Inhaltsliste, unbelegte Leistungsbehauptungen oder Anweisungen enthalten, die nirgends im Hauptteil vorkommen. Der TOC darf niemals manuell eingegebene Anker, Ziele außerhalb der aktuellen Seite oder Links zu leeren Abschnitten enthalten.

Richtlinie zur Ankerstabilität

Eine Überschriften-ID ist der Fragmentteil einer URL, wie z. B. #ankerstabilitätsrichtlinie (im Englischen #anchor-stability-policy). Veröffentlichte Fragment-URLs sind öffentliche Schnittstellen. Lesezeichen, Kampagnenlinks, Support-Dokumentation, Suchergebnisse und KI-generierte Antworten können direkt darauf verweisen. Die Änderung des Überschriftentextes kann die von Hugo generierte ID ändern und jeden eingehenden Anker ungültig machen, selbst wenn die Seiten-URL gleich bleibt.

Frieren Sie nach der Veröffentlichung die IDs aller H2- und H3-Überschriften ein. Bevorzugen Sie die Bearbeitung des Absatzes unter einer Überschrift gegenüber der Umbenennung der Überschrift. Wenn eine Umbenennung notwendig ist, bewahren Sie die alte ID über einen expliziten Anker-Mechanismus, der vom Publikationssystem unterstützt wird, und überprüfen Sie sowohl das alte eingehende Fragment als auch die neue TOC-Auswahl. Verwenden Sie niemals eine alte ID für ein anderes Thema wieder, duplizieren Sie niemals eine ID auf der Seite und übersetzen Sie niemals eine ID auf einer bestehenden lokalisierten URL ohne einen Migrationsplan. Halten Sie absichtliche Ankeränderungen im Versionshinweis oder im Inhaltsänderungsprotokoll fest, damit Besitzer bekannter eingehender Links diese aktualisieren können.

Beitragstypen, die es verwenden

Das Frontmatter postTypes listet die Formate auf, für die dieses Element Teil des Produktionsmusters ist. Es ist dennoch bedingt: Eine kurze Instanz eines normalerweise langen Formats kann unterhalb des TOC-Schwellenwerts liegen.

Produkt-, Kategorie- und Anwendungsfallseiten sind standardmäßig nicht enthalten, da ihre primären Reisen oft durch Seiten-Navigation und Handlungsaufforderungen abgedeckt werden. Fügen Sie dieses Element nur durch eine dokumentierte Vorlagenentscheidung hinzu, nicht weil die Seite zufällig lang ist.

QA-Checkliste

• Bestätigen Sie, dass die Seite den Schwellenwert erreicht: mindestens 1.800 Wörter, sieben H2-Abschnitte oder ein dokumentierter nicht-linearer Navigationsbedarf.
• Bestätigen Sie, dass der Überblick 40–90 Wörter umfasst und Umfang, beabsichtigtes Ergebnis und notwendige Ausschlüsse angibt.
• Bestätigen Sie, dass der Überblick nicht die direkte Antwort oder die wichtigen Erkenntnisse wiederholt.
• Bestätigen Sie, dass der Shortcode einmal erscheint, unmittelbar nach dem Überblick und vor der ersten H2.
• Bestätigen Sie, dass jede H2 ein sinnvolles Hauptziel ist und jede H3 nützlich genug ist, um in der Navigation zu erscheinen.
• Bestätigen Sie, dass die generierte Liste 5–18 Einträge enthält, eine logische Reihenfolge verwendet und unter der aktuellen Konfiguration keine H4-Einträge enthält.
• Bestätigen Sie, dass config/_default/markup.toml noch startLevel = 2, endLevel = 3 und ordered = false verwendet, oder aktualisieren Sie diese Spezifikation mit der Komponentenänderung.
• Bestätigen Sie, dass eine Seite ohne berechtigte H2 nicht behauptet, einen TOC zu enthalten; der Shortcode wird stillschweigend nichts rendern.
• Bestätigen Sie, dass jedes generierte Fragment eindeutig ist und die beabsichtigte Überschrift erreicht.
• Testen Sie veröffentlichte eingehende Anker-URLs, bevor Sie eine H2- oder H3-Formulierung ändern; bewahren Sie alte IDs, wenn Überschriften geändert werden müssen.
• Überprüfen Sie auf Desktop, dass der sticky Wrapper bei 300 Pixeln oder weniger verborgen ist und nach Überschreiten der Scrollposition von 300 Pixeln erscheint.
• Überprüfen Sie, dass der fixierte Wrapper unterhalb des tatsächlichen Headers sitzt, der Fortschrittsbalken vorrückt und das aktive Label Abschnittsänderungen folgt.
• Überprüfen Sie, dass schmale Viewports das aktuelle Steuerelement nicht anzeigen, und dokumentieren Sie dies als erwartetes aktuelles Verhalten und nicht als defekten Screenshot.
• Dokumentieren Sie die aktuellen Barrierefreiheitseinschränkungen: keine Navigations-Landmarke, kein tastaturfokussierbarer sichtbarer Auslöser, keine Fokusübertragung, keine Fragmentaktualisierung und kein Zweig für reduzierte Bewegung.
• Bestätigen Sie, dass kein Screenshot-Pfad gerendert wird, bis das entsprechende Asset auf der Festplatte existiert.

FAQ

Die folgenden Fragen decken die redaktionellen Entscheidungen ab, die am häufigsten dazu führen, dass dieses Element zu früh hinzugefügt, zu tief gemacht oder nach der Veröffentlichung beschädigt wird.