Spis treści: Format i zasady

W bibliotece elementów szybki przegląd i spis treści informują czytelników, co obejmuje dana strona, w czym pomoże im podjąć decyzję i jak przeskoczyć do potrzebnej sekcji.

Szybki przegląd. Użyj tego sparowanego elementu otwierającego na długich lub złożonych strukturalnie stronach. Napisz przegląd liczący 40–90 słów, który określa zakres i oczekiwany rezultat, a następnie podaj listę treści utworzoną ze stabilnych nagłówków H2 i tylko użytecznych nagłówków H3. Na tej stronie panel sterowania treścią pozostaje ukryty, dopóki czytelnik nie przewinie dalej niż 300 pikseli; następnie pojawia się jako stały rozwijany panel na pulpicie pod nagłówkiem witryny.

Dlaczego ten element jest ważny

Czytelnicy nie zaczynają każdej długiej strony w tym samym miejscu. Jedna osoba potrzebuje definicji, inna chce poznać kroki wdrożenia, a trzecia sprawdza pojedyncze ograniczenie przed zatwierdzeniem pracy. Krótki przegląd odpowiada na pytanie „Czy jestem we właściwym miejscu?”, zanim czytelnik zainwestuje uwagę. Lista treści odpowiada na pytanie „Gdzie jest część, której potrzebuję?”, bez wymuszania linearného czytania.

Te dwie części są określone razem, ponieważ rozwiązują sąsiadujące, ale różne problemy orientacyjne. Przegląd wyjaśnia obietnicę strony, granice i użyteczny rezultat w zdaniach. Lista treści ukazuje drogę przez tę obietnicę jako lokalizacje. Lista treści bez przeglądu może pokazać, że strona ma sekcje o nazwach „Konfiguracja” i „Dostępność”, ale nie może wyjaśnić, czy strona jest koncepcyjnym wprowadzeniem, czy specyfikacją produkcyjną. Przegląd bez nawigacji może ustalić zakres, ale nadal zmusza czytelnika do przeszukiwania 3000 słów.

Ten element poprawia również ekstrahowalność maszynową, czyli zdolność oprogramowania do wyizolowania fragmentu i zachowania jego przeznaczenia poza pełną stroną. Przegląd jest drugim zwięzłym, samodzielnym podsumowaniem po tytule i opisie. Źródłowy spis treści Hugo to połączony, czytelny maszynowo zarys zakresu i hierarchii strony; obecny renderer sticky przekształca te linki w opcje, które zachowują swoje wartości fragmentów URL, czyli część #sekcja adresu URL. Systemy wyszukiwania, narzędzia do wyszukiwania, rozszerzenia przeglądarki i agenty AI mogą użyć zarysu dokumentu do zidentyfikowania prawdopodobnych obszarów odpowiedzi przed przetworzeniem każdego akapitu. Nie gwarantuje to funkcji wyszukiwania ani cytowania przez AI; zmniejsza to niejednoznaczność co do tego, gdzie zaczynają się tematy i jak są ze sobą powiązane.

Połączenie nie może tworzyć powtórzeń. Przegląd określa zakres i rezultat. Blok bezpośredniej odpowiedzi odpowiada na główne pytanie. Kluczowe wnioski określają wnioski warte zapamiętania. Gdy wszystkie trzy mówią to samo w różnych ramkach, otwarcie staje się przeszkodą, a nie pomocą.

Kiedy go używać

Lista treści zasługuje na swoje miejsce, gdy przeskakiwanie jest prawdopodobnym zachowaniem czytelnika. Liczba słów jest użytecznym wskaźnikiem, ale struktura jest czynnikiem decydującym.

Używaj samego przeglądu, gdy tytuł może być interpretowany szeroko, gdy strona celowo wyklucza sąsiadujące tematy lub gdy czytelnik musi znać oczekiwany rezultat przed kontynuowaniem. 900-słowna strona polityki może potrzebować dwuzdaniowego przeglądu, nawet jeśli nie potrzebuje nawigacji.

Używaj samej listy treści tylko wtedy, gdy tytuł i otwarcie już czynią zakres bezdyskusyjnym. To bliskie chybienie jest powszechne na stronach referencyjnych: otwarcie może zawierać bezpośrednią definicję, która spełnia rolę orientacyjną, podczas gdy długi zestaw niezależnych pól nadal potrzebuje nawigacji.

Nie używaj żadnej z części jako dekoracji. Sześciopunktowy spis treści na 700-słownym artykule dodaje dodatkową decyzję przed odpowiedzią. Przegląd, który mówi „Ten przewodnik omawia wszystko, co musisz wiedzieć”, nie definiuje zakresu, rezultatu ani wykluczeń. Nie używaj pary do ukrywania słabej struktury nagłówków: jeśli nagłówki nakładają się, używają niespójnej gramatyki lub dzielą jeden pomysł na wiele małych sekcji, najpierw napraw dokument, a potem ujawniaj jego zarys.

Gdzie go umieścić

Pozycja jest częścią znaczenia elementu. Przegląd musi pojawić się po hero lub otwierającej bezpośredniej odpowiedzi, a przed pierwszym nagłówkiem H2. Może to być krótki akapit lub zwięzła lista, ale musi zostać napotkany, zanim czytelnik zaangażuje się w treść główną. Wywołanie spisu treści należy umieścić bezpośrednio po przeglądzie, aby autorskie źródło utrzymywało orientację i nawigację razem, nawet jeśli przylepny panel sterowania tej witryny staje się widoczny dopiero po przewinięciu 300 pikseli.

Para nie może przerywać definicji, oddzielać twierdzenia od jego dowodów ani pojawiać się po raz pierwszy w połowie dokumentu. Nie umieszczaj go między nagłówkiem a otwierającym akapitem tego nagłówka: związek między nagłówkiem a wyjaśnieniem powinien pozostać bezpośredni. Nie umieszczaj innego komponentu typu przegląd bezpośrednio obok niego. Gdy wymagany jest blok bezpośredniej odpowiedzi lub kluczowych wniosków, przypisz odrębne zadania i użyj tej kolejności: bezpośrednia odpowiedź, krótki przegląd zakresu, wywołanie spisu treści, pierwsza sekcja treści. Pomiń jedno z podsumowań, jeśli sformułowania nadal się pokrywają.

Użyj shortcode raz na stronę. Jego wyrenderowane ID (tocDropdown, tocSelect, selectTrigger i powiązane elementy sterujące) są stałe, więc druga instancja tworzy zduplikowane ID dokumentu i nieprzewidywalne skrypty.

Anatomia

Element ma sześć znaczących obszarów. Pierwsze pięć to treść lub zachowanie; wskaźnik postępu to status. Legenda jest przechowywana na stronie, aby pozostała czytelna po zmianie rozmiaru lub wymianie zrzutu ekranu.

1. Treść przeglądu: 40–90 słów określających zakres, zamierzony rezultat i wszelkie ważne granice.
2. Tytuł przylepnej ramki: domyślnie tytuł strony lub atrybut title pochodzący od autora, gdy krótsza etykieta jest czytelniejsza.
3. Etykieta bieżącej sekcji: zaczyna się od „Wybierz sekcję…” i zmienia się, gdy IntersectionObserver przeglądarki — API, które wykrywa elementy wchodzące do zdefiniowanego obszaru viewportu — oznacza sekcje jako aktywne.
4. Przycisk rozwijania: otwiera wygenerowaną listę lokalizacji sekcji po kliknięciu w obecnej implementacji.
5. Opcje nagłówków: linki pochodzące ze spisu treści strony w Hugo, obecnie H2 i H3 ze względu na markup.toml.
6. Pasek postępu: pokazuje proporcję całkowitego przewijalnego dokumentu, który został przebyty; nie identyfikuje ukończenia sekcji.

Przykłady projektowe

Galeria obejmuje stany zachowania, a nie motywy dekoracyjne. Bazowa treść pozostaje taka sama, aby recenzenci mogli porównać timing, hierarchię, przycinanie i interakcję.

Żadne alternatywne warianty wizualne nie są tworzone przez Markdown. title zmienia etykietę, a class dodaje klasy opakowania, ale żaden z nich nie tworzy semantycznie innego elementu. Nowe warianty kolorystyczne, karty, panele boczne lub listy wbudowane wymagają decyzji komponentu, a nie dowolnej klasy dodanej w treści.

Parametry

Przegląd i spis treści dzielą jedną umowę redakcyjną, ale tylko przylepny spis treści jest renderowany przez bieżący shortcode. Wartości konfiguracyjne są uwzględnione, ponieważ zmieniają wynik, mimo że autorzy nie mogą ich ustawić przy każdym wywołaniu.

Zależność łatwo przeoczyć: strona bez nagłówków H2 po cichu nie renderuje przylepnego spisu treści, ponieważ Hugo nie produkuje użytecznego zarysu, a partial emituje znaczniki tylko wtedy, gdy ma nagłówki. Przy obecnej konfiguracji kwalifikują się nagłówki H2 i ich potomkowie H3; nagłówki H4 i głębsze są wykluczone. Partial normalnie parsuje .TableOfContents Hugo. Jego HTML-owa rezerwa skanuje tylko wyrenderowane elementy H2, więc autorzy nie powinni polegać na zachowaniu rezerwowym w celu zachowania nawigacji H3.

Składnia i przykłady kodu

Przenośna notacja zachowuje przegląd jako treść elementu, a ustawienia nawigacji jako atrybuty. Linki nagłówków pozostają generowane z otaczającego dokumentu, a nie powielane przez autora.

:::quick-overview-and-toc{title="Na tej stronie" class=""}
Ten przewodnik wyjaśnia, kiedy używać elementu, jak zachowuje się przylepny panel Hugo
oraz jak zachować dostępne, stabilne lokalizacje sekcji po publikacji.
:::

Obecne mapowanie Hugo zapisuje przegląd jako zwykły Markdown i wywołuje dostarczony shortcode raz. Nie ma ciała JSON.

Ten przewodnik wyjaśnia, kiedy używać elementu, jak zachowuje się przylepny panel Hugo
oraz jak zachować dostępne, stabilne lokalizacje sekcji po publikacji.

{{< table-of-contents title="Na tej stronie" class="" >}}

Mapowanie bloku WordPress przechowuje tę samą treść i atrybuty. Witryna, która nie zarejestrowała bloku, może użyć równoważnej formy shortcode; nie może ręcznie tworzyć linków nagłówków.

<!-- wp:amicited/quick-overview-and-toc {"title":"Na tej stronie","className":""} -->
<p>Ten przewodnik wyjaśnia, kiedy używać elementu, jak zachowuje się przylepny panel
i jak zachować dostępne, stabilne lokalizacje sekcji po publikacji.</p>
<!-- /wp:amicited/quick-overview-and-toc -->

[amicited_quick_overview_toc title="Na tej stronie" class=""]
Ten przewodnik wyjaśnia zakres elementu, jego zachowanie i politykę kotwic.
[/amicited_quick_overview_toc]

We wszystkich trzech systemach źródłem prawdy jest rzeczywista hierarchia nagłówków dokumentu. Ręcznie utrzymywana lista będzie dryfować wraz ze zmianami nagłówków i może wskazywać na ID, które już nie istnieją.

Przykłady

Dobry przykład

Szybki przegląd. Ten przewodnik pokazuje zespołom treści, jak planować, pisać, recenzować i utrzymywać stronę porównawczą. Obejmuje standardy dowodowe, kryteria porównania, twierdzenia produktowe, dostępne tabele i kontrole po publikacji. Nie obejmuje płatnych miejsc ani prowizji afiliacyjnych.

Na tej stronie: Zdefiniuj decyzję · Wybierz kryteria porównania · Zbierz dowody · Przygotuj stronę · Zweryfikuj twierdzenia · Mierz i utrzymuj

To działa, ponieważ przegląd określa odbiorców, rezultat, zakres i granicę w 48 słowach. Sześć lokalizacji to odrębne zadania, do których czytelnik może wracać niezależnie. Ich etykiety używają równoległych form czasownikowych, więc zarówno ludzie, jak i maszyny mogą wywnioskować proces. Żaden z wpisów nie powtarza tytułu strony ani nie ujawnia trywialnego podrozdziału.

Zły przykład

Przegląd: Witamy w naszym kompletnym przewodniku. W dzisiejszym zmieniającym się świecie jest wiele do poznania, więc czytaj dalej, aby dowiedzieć się wszystkiego.

Spis treści: Wprowadzenie · Więcej informacji · Ważne rzeczy · Inne rzeczy · Podsumowanie

To zawodzi z dwóch powodów. Przegląd wydaje 22 słowa bez określenia zakresu, czytelnika, rezultatu ani wykluczeń. Wpisy etykietują kontenery retoryczne, a nie tematy, więc nie pomagają czytelnikowi przewidzieć, gdzie znajduje się odpowiedź. Dodanie większej liczby nagłówków nie naprawi tego; dokument najpierw potrzebuje znaczących granic sekcji.

Drugie bliskie chybienie to 600-słowna odpowiedź z nagłówkami „Przegląd”, „Tło”, „Szczegóły”, „Wskazówki” i „Podsumowanie” w spisie treści. Nawet jeśli każda kotwica działa, lista dodaje więcej interfejsu niż wartości nawigacyjnej. Zachowaj bezpośrednie otwarcie i usuń spis treści.

Znaczniki schematu i dostępność

Tutaj znaczniki schematu oznaczają ustandaryzowany kod czytelny maszynowo, który identyfikuje byty i właściwości. Ten element nie ma dedykowanego typu ani właściwości w słowniku Schema.org, a shortcode Hugo nie emituje JSON-LD, notacji opartej na skryptach powszechnie używanej do publikowania tego słownictwa. Nie oznaczaj spisu treści jako ItemList tylko dlatego, że jest listą; sugerowałoby to listę elementów tematycznych, a nie nawigację. Przegląd może informować description strony tylko wtedy, gdy sformułowanie jest samodzielnie odpowiednie, ale nie jest automatycznie kopiowane do danych strukturalnych.

Zachowanie HTML i ARIA jest tutaj ważniejsze. ARIA, standard Accessible Rich Internet Applications, dostarcza role, nazwy i stany, gdy natywny HTML tego nie robi. Landmark to nazwany obszar strony, do którego użytkownicy technologii asystujących mogą przeskoczyć. Focus to bieżący cel interakcji klawiaturowej.

To fakty implementacyjne, a nie pozwolenie na ignorowanie dostępności. Recenzenci treści mogą dziś zweryfikować czytelność nagłówków, unikalność ID i logiczną kolejność. Właściciele komponentów muszą rozwiązać kwestie wyzwalacza, landmarka, focusu, URL i zachowania przy zredukowanym ruchu, zanim opiszą przylepny wariant jako dostępny z klawiatury.

Zasady pisania

Napisz przegląd po ustabilizowaniu struktury strony. Zapobiega to oddalaniu się wczesnej obietnicy od ukończonego zakresu. Utrzymuj go między 40 a 90 słowami. Preferuj dwa lub trzy zdania; używaj trzech do pięciu punktów tylko wtedy, gdy strona zawiera kilka naprawdę równoległych rezultatów. Określ, co strona pomaga czytelnikowi zrozumieć, zdecydować lub zrobić. Wymień wykluczenie, gdy tytuł może rozsądnie obiecywać więcej, niż strona dostarcza.

Używaj H2 dla głównych pytań, etapów lub obszarów decyzyjnych strony. Uwzględniaj H3 w nawigacji tylko wtedy, gdy jest to użyteczna niezależna lokalizacja w ramach obszernego nagłówka H2. Na tej stronie konfiguracja automatycznie obejmuje każdy H2 i H3, więc praktyczna polityka jest bardziej rygorystyczna: nie twórz nagłówka, chyba że zasługuje na pojawienie się w nawigacji. Celuj w 5–18 łącznych wpisów. Jeśli wygenerowana lista przekracza 18, połącz nakładające się sekcje, usuń niepotrzebne nagłówki H3 lub podziel stronę. Nigdy nie przeskakuj bezpośrednio z H2 do H4, aby ukryć nagłówek przed spisem treści; poziomy nagłówków wyrażają hierarchię, a nie stylizację lub preferencję nawigacyjną.

Używaj zwięzłego, opisowego tekstu nagłówków. Czytelnik powinien rozumieć każdą lokalizację bez czytania jej akapitu nadrzędnego. Preferuj równoległe formy w obrębie sekwencji: „Wybierz kryteria”, „Zbierz dowody” i „Zweryfikuj twierdzenia” są łatwiejsze do skanowania niż mieszanka rzeczowników, pytań i niejasnych etykiet. Nie umieszczaj cytatów, twierdzeń promocyjnych, emoji, znaczników statusu ani pełnych zdań w nagłówku wyłącznie po to, by wpłynąć na spis treści.

Przegląd nigdy nie może zawierać drugiej miniaturowej listy treści, niepopartych twierdzeń o wydajności ani instrukcji, które nie pojawiają się nigdzie w treści. Spis treści nigdy nie może zawierać ręcznie wpisanych kotwic, lokalizacji poza bieżącą stroną ani linków do pustych sekcji.

Polityka stabilności kotwic

ID nagłówka to część fragmentu URL, na przykład #stabilnosc-kotwic. Opublikowane fragmenty URL to publiczne interfejsy. Zakładki, linki kampanii, dokumentacja wsparcia, wyniki wyszukiwania i odpowiedzi generowane przez AI mogą wskazywać bezpośrednio na nie. Zmiana tekstu nagłówka może zmienić wygenerowane ID Hugo i złamać każdą przychodzącą kotwicę, nawet jeśli URL strony pozostaje ten sam.

Po publikacji zamroź ID wszystkich nagłówków H2 i H3. Preferuj edycję akapitu pod nagłówkiem zamiast zmiany nazwy nagłówka. Gdy zmiana nazwy jest konieczna, zachowaj stare ID za pomocą mechanizmu jawnej kotwicy obsługiwanego przez system publikacji, a następnie zweryfikuj zarówno stary przychodzący fragment, jak i nowy wybór w spisie treści. Nigdy nie używaj ponownie starego ID dla innego tematu, nigdy nie duplikuj ID na stronie i nigdy nie tłumacz ID na istniejącym zlokalizowanym URL bez planu migracji. Zapisz celowe zmiany kotwic w notatce wydania lub dzienniku zmian treści, aby właściciele znanych linków przychodzących mogli je zaktualizować.

Typy postów, które go używają

Frontmatter postTypes wymienia formaty, dla których ten element jest częścią wzorca produkcyjnego. Jest nadal warunkowy: krótki przypadek normalnie długiego formatu może spaść poniżej progu spisu treści.

Strony produktów, kategorii i przypadków użycia nie są domyślnie uwzględniane, ponieważ ich główne ścieżki są często obsługiwane przez nawigację na poziomie strony i wezwania do działania. Dodaj ten element tylko przez udokumentowaną decyzję szablonu, a nie dlatego, że strona jest akurat długa.

Lista kontrolna QA

• Potwierdź, że strona spełnia próg: co najmniej 1800 słów, siedem sekcji H2 lub udokumentowana potrzeba nielinearnej nawigacji.
• Potwierdź, że przegląd ma 40–90 słów i określa zakres, zamierzony rezultat i wszelkie konieczne wykluczenia.
• Potwierdź, że przegląd nie powtarza bezpośredniej odpowiedzi ani kluczowych wniosków.
• Potwierdź, że shortcode pojawia się raz, bezpośrednio po przeglądzie i przed pierwszym nagłówkiem H2.
• Potwierdź, że każdy H2 jest znaczącą główną lokalizacją, a każdy H3 jest wystarczająco użyteczny, by pojawić się w nawigacji.
• Potwierdź, że wygenerowana lista zawiera 5–18 wpisów, używa logicznej kolejności i nie zawiera elementów H4 przy obecnej konfiguracji.
• Potwierdź, że config/_default/markup.toml nadal używa startLevel = 2, endLevel = 3 i ordered = false, lub zaktualizuj tę specyfikację o zmiany w komponencie.
• Potwierdź, że strona bez kwalifikującego się H2 nie twierdzi, że zawiera spis treści; shortcode po cichu nic nie wyrenderuje.
• Potwierdź, że każdy wygenerowany fragment jest unikalny i dociera do zamierzonego nagłówka.
• Przetestuj opublikowane przychodzące adresy URL kotwic przed zmianą dowolnego sformułowania H2 lub H3; zachowaj stare ID, gdy nagłówki muszą się zmienić.
• Na pulpicie sprawdź, czy przylepna ramka jest ukryta przy 300 pikselach lub mniej i pojawia się po przekroczeniu 300 pikseli przewijania.
• Sprawdź, czy stała ramka znajduje się pod rzeczywistym nagłówkiem, pasek postępu się przesuwa, a aktywna etykieta podąża za zmianami sekcji.
• Sprawdź, czy wąskie viewporty nie pokazują obecnego panelu sterowania i odnotuj to jako oczekiwane bieżące zachowanie, a nie jako zepsuty zrzut ekranu.
• Zapisz bieżące ograniczenia dostępności: brak landmarka nawigacyjnego, brak widocznego wyzwalacza osiągalnego klawiaturą, brak transferu focusu, brak aktualizacji fragmentu i brak gałęzi dla zredukowanego ruchu.
• Potwierdź, że żadna ścieżka zrzutu ekranu nie jest renderowana, dopóki odpowiedni zasób nie istnieje na dysku.

FAQ

Poniższe pytania dotyczą decyzji redakcyjnych, które najczęściej powodują, że ten element jest dodawany zbyt wcześnie, robiony zbyt głęboko lub psuty po publikacji.