Obsah: Formát a pravidla

V knihovně prvků rychlý přehled a obsah říkají čtenářům, co stránka pokrývá, s čím jim pomůže rozhodnout se a jak přeskočit na sekci, kterou potřebují.

Rychlý přehled. Použijte tento párový úvodní prvek na dlouhých nebo strukturně složitých stránkách. Napište přehled o 40–90 slovech, který stanoví rozsah a očekávaný výsledek, poté poskytněte seznam obsahu vytvořený ze stabilních nadpisů H2 a pouze užitečných nadpisů H3. Na tomto webu zůstává ovládací prvek obsahu níže skrytý, dokud čtenář neposune stránku o více než 300 pixelů; poté se zobrazí jako pevný desktopový rozbalovací seznam pod hlavičkou webu.

Proč na tomto prvku záleží

Čtenáři nezačínají každou dlouhou stránku na stejném místě. Jeden člověk potřebuje definici, druhý chce kroky implementace a třetí kontroluje jediné omezení před schválením práce. Krátký přehled odpovídá na otázku „Jsem na správném místě?“ dříve, než čtenář investuje pozornost. Seznam obsahu odpovídá na otázku „Kde je část, kterou potřebuji?“ bez nutnosti lineárního čtení.

Obě části jsou specifikovány společně, protože řeší sousední, ale odlišné orientační problémy. Přehled vysvětluje příslib stránky, hranice a užitečný výsledek ve větách. Seznam obsahu odhaluje cestu skrze tento příslib jako cíle. Seznam obsahu bez přehledu může ukázat, že stránka má sekce nazvané „Konfigurace“ a „Přístupnost“, ale nedokáže vysvětlit, zda je stránka koncepčním úvodem nebo produkční specifikací. Přehled bez navigace může stanovit rozsah, ale přesto donutí čtenáře prohledávat 3 000 slov.

Tento prvek také zlepšuje strojovou extrahovatelnost, tedy schopnost softwaru izolovat pasáž a zachovat její účel mimo celou stránku. Přehled je druhým stručným, samostatným shrnutím po titulku a popisu. Zdrojový obsah Hugo je propojený, strojově čitelný nástin pokrytí a hierarchie stránky; aktuální sticky renderer převádí tyto odkazy na možnosti, které si zachovávají své hodnoty URL fragmentů, část #section URL. Vyhledávací systémy, nástroje pro vyhledávání, rozšíření prohlížeče a AI agenti mohou použít nástin dokumentu k identifikaci pravděpodobných oblastí odpovědí dříve, než zpracují každý odstavec. To nezaručuje vyhledávací funkci nebo citaci AI; snižuje to nejednoznačnost ohledně toho, kde témata začínají a jak spolu souvisejí.

Párování nesmí vytvářet opakování. Přehled uvádí rozsah a výsledek. Blok přímé odpovědi odpovídá na primární otázku. Klíčové poznatky uvádějí závěry, které stojí za zapamatování. Když všechny tři říkají totéž v různých boxech, úvod se stává překážkou, nikoli pomůckou.

Kdy to použít

Seznam obsahu si zaslouží své místo, když je přeskakování pravděpodobným chováním čtenáře. Počet slov je užitečným ukazatelem, ale struktura je rozhodujícím faktorem.

Použijte samotný přehled, když by titulek mohl být vykládán široce, když stránka záměrně vylučuje sousední témata nebo když čtenář potřebuje znát očekávaný výsledek před pokračováním. 900slovná stránka s politikou může potřebovat dvouvětý přehled, i když nepotřebuje navigaci.

Použijte samotný seznam obsahu pouze tehdy, když titulek a úvod již činí rozsah nezaměnitelným. Tento téměř zásah je běžný u referenčních stránek: úvod může obsahovat přímou definici, která plní orientační úlohu, zatímco dlouhá sada nezávislých polí stále potřebuje navigaci.

Nepoužívejte žádnou z částí jako dekoraci. Šestipoložkový TOC na 700slovném článku přidává další rozhodnutí před odpovědí. Přehled, který říká „Tento průvodce zkoumá vše, co potřebujete vědět,“ nedefinuje rozsah, výsledek ani vyloučení. Nepoužívejte dvojici k zakrytí slabé struktury nadpisů: pokud se nadpisy překrývají, používají nekonzistentní gramatiku nebo rozdělují jednu myšlenku do mnoha malých sekcí, nejprve opravte dokument, než odhalíte jeho nástin.

Kam to umístit

Umístění je součástí významu prvku. Přehled se musí objevit za hero sekcí nebo úvodní přímou odpovědí a před prvním H2. Může to být krátký odstavec nebo kompaktní seznam, ale musí být zaznamenán dříve, než se čtenář zaváže k tělu stránky. Volání TOC patří bezprostředně za přehled, aby zdrojový text udržoval orientaci a navigaci pohromadě, i když se sticky ovládací prvek tohoto webu stane viditelným až po posunu o 300 pixelů.

Dvojice nesmí přerušit definici, oddělit tvrzení od jeho důkazu ani se objevit poprvé uprostřed dokumentu. Neumísťujte ji mezi nadpis a jeho úvodní odstavec: vztah mezi nadpisem a vysvětlením by měl zůstat přímý. Neumísťujte další komponentu typu přehledu bezprostředně vedle ní. Pokud je vyžadován blok přímé odpovědi nebo klíčových poznatků, přidělte odlišné úkoly a použijte toto pořadí: přímá odpověď, krátký přehled rozsahu, volání TOC, první tělový oddíl. Vynechte jedno ze shrnutí, pokud se znění stále překrývá.

Použijte shortcode jednou na stránku. Jeho renderovaná ID (tocDropdown, tocSelect, selectTrigger a související ovládací prvky) jsou pevná, takže druhá instance vytváří duplicitní ID dokumentu a nepředvídatelné skripty.

Anatomie

Prvek má šest významných oblastí. Prvních pět je obsah nebo chování; indikátor průběhu je stav. Legenda je ponechána na stránce, aby zůstala čitelná při změně velikosti nebo nahrazení snímku obrazovky.

1. Tělo přehledu: 40–90 slov uvádějících rozsah, zamýšlený výsledek a jakoukoli důležitou hranici.
2. Titulek sticky obalu: výchozí titulek stránky nebo autorův atribut title, pokud je kratší popisek jasnější.
3. Popisek aktuální sekce: začíná jako „Vyberte sekci…“ a mění se, jak IntersectionObserver prohlížeče, API detekující vstup prvků do definované oblasti výřezu, označuje sekce jako aktivní.
4. Spouštěč rozbalovacího seznamu: po kliknutí otevře vygenerovaný seznam cílových sekcí v aktuální implementaci.
5. Možnosti nadpisů: odkazy odvozené z obsahu stránky Hugo, v současnosti H2 a H3 kvůli markup.toml.
6. Indikátor průběhu: ukazuje podíl z celkového rolovatelného dokumentu; neurčuje dokončení sekce.

Příklady designu

Galerie pokrývá stavy chování spíše než dekorativní motivy. Základní obsah zůstává stejný, aby recenzenti mohli porovnávat načasování, hierarchii, ořezávání a interakci.

Prostřednictvím Markdown nejsou vytvářeny žádné alternativní vizuální varianty. title mění popisek a class přidává třídy obalu, ale ani jedno nevytváří sémanticky odlišný prvek. Nová barevná, karetní, postranní nebo inline seznamová úprava vyžaduje rozhodnutí o komponentě, nikoli libovolnou třídu přidanou v obsahu.

Parametry

Přehled a TOC sdílejí jednu redakční smlouvu, ale pouze sticky TOC je renderován aktuálním shortcodeem. Konfigurační hodnoty jsou zahrnuty, protože mění výstup, i když je autoři nemohou nastavit při každém volání.

Závislost lze snadno přehlédnout: stránka bez nadpisů H2 tiše nevykreslí žádný sticky TOC, protože Hugo nevytvoří použitelný nástin a částečný kód vydá HTML pouze tehdy, když má záhlaví. Při aktuální konfiguraci jsou způsobilé H2 a jejich potomci H3; H4 a hlubší nadpisy jsou vyloučeny. Částečný kód běžně parsuje Hugo .TableOfContents. Jeho HTML záložní řešení skenuje pouze renderované prvky H2, takže autoři se nesmí spoléhat na záložní chování pro zachování navigace H3.

Syntaxe a příklady kódu

Přenosný zápis ponechává přehled jako tělo prvku a nastavení navigace jako atributy. Odkazy nadpisů zůstávají generovány z okolního dokumentu, nikoli duplikovány autorem.

:::quick-overview-and-toc{title="On this page" class=""}
Tento průvodce vysvětluje, kdy prvek použít, jak se chová sticky Hugo ovládací prvek
a jak zachovat přístupné a stabilní cíle sekcí po publikaci.
:::

Aktuální Hugo mapování zapisuje přehled jako běžný Markdown a jednou vyvolá dodaný shortcode. Neexistuje žádné JSON tělo.

Tento průvodce vysvětluje, kdy prvek použít, jak se chová sticky Hugo ovládací prvek
a jak zachovat přístupné a stabilní cíle sekcí po publikaci.

{{< table-of-contents title="On this page" class="" >}}

WordPress blokové mapování ukládá stejné tělo a atributy. Web, který blok nezaregistroval, může použít ekvivalentní formu shortcode; nesmí ručně vytvářet odkazy nadpisů.

<!-- wp:amicited/quick-overview-and-toc {"title":"On this page","className":""} -->
<p>Tento průvodce vysvětluje, kdy prvek použít, jak se chová sticky ovládací prvek
a jak zachovat přístupné a stabilní cíle sekcí po publikaci.</p>
<!-- /wp:amicited/quick-overview-and-toc -->

[amicited_quick_overview_toc title="On this page" class=""]
Tento průvodce vysvětluje rozsah prvku, chování a politiku kotev.
[/amicited_quick_overview_toc]

Napříč všemi třemi systémy je zdrojem pravdy skutečná hierarchie nadpisů dokumentu. Ručně udržovaný seznam se bude s měnícími se nadpisy rozcházet a může ukazovat na ID, která již neexistují.

Příklady

Dobrý příklad

Rychlý přehled. Tento průvodce ukazuje obsahovým týmům, jak plánovat, psát, recenzovat a udržovat srovnávací stránku. Pokrývá standardy důkazů, srovnávací kritéria, produktová tvrzení, přístupné tabulky a kontroly po publikaci. Nezabývá se placeným umístěním ani provizemi z affiliate programů.

Na této stránce: Definujte rozhodnutí · Vyberte srovnávací kritéria · Shromážděte důkazy · Napište stránku · Zkontrolujte tvrzení · Měřte a udržujte

Toto funguje, protože přehled pojmenovává publikum, výsledek, pokrytí a hranici ve 48 slovech. Šest cílů jsou odlišné úkoly, které může čtenář znovu samostatně navštívit. Jejich popisky používají paralelní slovesné fráze, takže lidé i stroje mohou odvodit proces. Žádná z položek neopakuje titulek stránky ani neodhaluje triviální podsekci.

Špatný příklad

Přehled: Vítejte v našem kompletním průvodci. V dnešním měnícím se světě je toho hodně k vědění, takže čtěte dále a dozvíte se vše.

Obsah: Úvod · Další informace · Důležité věci · Ostatní věci · Závěr

Toto selhává ze dvou důvodů. Přehled spotřebuje 22 slov, aniž by definoval rozsah, čtenáře, výsledek nebo vyloučení. Položky označují rétorické nádoby spíše než témata, takže nepomáhají čtenáři předvídat, kde odpověď žije. Přidání dalších nadpisů by to nevyřešilo; dokument nejprve potřebuje smysluplné hranice sekcí.

Druhým téměř zásahem je 600slovná odpověď s „Přehledem,“ „Pozadím,“ „Detaily,“ „Tipy“ a „Závěrem“ v jejím TOC. I když každá kotva funguje, seznam přidává více rozhraní než navigační hodnoty. Ponechte přímý úvod a odstraňte TOC.

Schema markup a přístupnost

Zde schema markup znamená standardizovaný strojově čitelný kód, který identifikuje entity a vlastnosti. Tento prvek nemá žádný vyhrazený typ nebo vlastnost ve slovníku Schema.org a Hugo shortcode nevydává JSON-LD, zápis založený na skriptech běžně používaný k publikování tohoto slovníku. Neoznačujte TOC jako ItemList jen proto, že je to seznam; to by naznačovalo seznam věcných položek spíše než navigaci. Přehled může informovat description stránky pouze tehdy, když je znění samostatně vhodné, ale není automaticky kopírováno do strukturovaných dat.

HTML a ARIA chování jsou zde důležitější. ARIA, standard Accessible Rich Internet Applications, poskytuje role, názvy a stavy tam, kde nativní HTML nestačí. Landmark je pojmenovaná oblast stránky, na kterou mohou uživatelé asistenčních technologií přeskočit. Focus je aktuální cíl interakce klávesnicí.

Toto jsou implementační fakta, nikoli povolení ignorovat přístupnost. Recenzenti obsahu mohou dnes ověřit jasnost nadpisů, jedinečná ID a logické pořadí. Vlastníci komponent musí vyřešit chování spouštěče, landmarku, focusu, URL a omezeného pohybu, než popíší sticky variantu jako přístupnou klávesnicí.

Pravidla psaní

Napište přehled až po ustálení struktury stránky. To zabrání tomu, aby se raný příslib odchýlil od hotového pokrytí. Udržujte jej mezi 40 a 90 slovy. Preferujte dvě nebo tři věty; použijte tři až pět odrážek pouze tehdy, když stránka obsahuje několik skutečně paralelních výsledků. Uveďte, s čím stránka pomáhá čtenáři porozumět, rozhodnout se nebo co udělat. Pojmenujte vyloučení, když by titulek mohl rozumně slibovat více, než stránka dodává.

Používejte H2 pro hlavní otázky, fáze nebo rozhodovací oblasti stránky. Zahrňte H3 do navigace pouze tehdy, když je užitečným nezávislým cílem v rámci významného H2. Na tomto webu konfigurace automaticky zahrnuje každý H2 a H3, takže praktická politika je přísnější: nevytvářejte nadpis, pokud si nezaslouží objevit se v navigaci. Cílejte na 5–18 celkových položek. Pokud vygenerovaný seznam přesáhne 18, slučte překrývající se sekce, odstraňte nepotřebné nadpisy H3 nebo stránku rozdělte. Nikdy nepřeskakujte přímo z H2 na H4, abyste skryli nadpis před TOC; úrovně nadpisů vyjadřují hierarchii, nikoli stylování nebo preferenci navigace.

Používejte stručný, popisný text nadpisu. Čtenář by měl rozumět každému cíli bez čtení jeho nadřazeného odstavce. Preferujte paralelní formy v rámci sekvence: „Zvolte kritéria,“ „Shromážděte důkazy“ a „Zkontrolujte tvrzení“ se skenují snadněji než směs podstatných jmen, otázek a vágních popisků. Nevkládejte citace, propagační tvrzení, emodži, stavové odznaky nebo celé věty do nadpisu pouze kvůli ovlivnění TOC.

Přehled nikdy nesmí obsahovat druhý miniaturní seznam obsahu, nepodložená tvrzení o výkonu nebo instrukce, které se nikde v těle neobjevují. TOC nikdy nesmí obsahovat ručně psané kotvy, cíle mimo aktuální stránku nebo odkazy na prázdné sekce.

Politika stability kotev

ID nadpisu je fragmentová část URL, například #anchor-stability-policy. Publikované fragmentové URL jsou veřejná rozhraní. Záložky, kampaně, podpůrná dokumentace, výsledky vyhledávání a AI generované odpovědi mohou na ně přímo odkazovat. Změna textu nadpisu může změnit generované ID v Hugo a zlomit každou příchozí kotvu, i když URL stránky zůstane stejná.

Po publikaci zmrazte ID všech nadpisů H2 a H3. Preferujte úpravu odstavce pod nadpisem před přejmenováním nadpisu. Když je přejmenování nezbytné, zachovejte staré ID pomocí mechanismu explicitních kotev podporovaného publikačním systémem, poté ověřte jak starý příchozí fragment, tak nový výběr TOC. Nikdy nepoužívejte staré ID pro jiné téma, nikdy neduplikujte ID na stránce a nikdy nepřekládejte ID na existující lokalizované URL bez migračního plánu. Zaznamenejte záměrné změny kotev v poznámce k vydání nebo protokolu změn obsahu, aby je vlastníci známých příchozích odkazů mohli aktualizovat.

Typy příspěvků, které jej používají

Frontmatter postTypes uvádí formáty, pro které je tento prvek součástí výrobního vzoru. Je stále podmíněný: krátká instance normálně dlouhého formátu může klesnout pod práh TOC.

Produktové, kategorické a případové stránky nejsou standardně zahrnuty, protože jejich primární cesty jsou často řízeny navigací na úrovni stránky a výzvami k akci. Přidejte tento prvek pouze na základě zdokumentovaného rozhodnutí šablony, ne proto, že je stránka náhodou dlouhá.

QA kontrolní seznam

• Potvrďte, že stránka splňuje práh: alespoň 1 800 slov, sedm sekcí H2 nebo zdokumentovaná potřeba nelineární navigace.
• Potvrďte, že přehled má 40–90 slov a uvádí rozsah, zamýšlený výsledek a případné nutné vyloučení.
• Potvrďte, že přehled neopakuje přímou odpověď ani klíčové poznatky.
• Potvrďte, že shortcode se objeví jednou, bezprostředně za přehledem a před prvním H2.
• Potvrďte, že každý H2 je smysluplným hlavním cílem a každý H3 je dostatečně užitečný, aby se objevil v navigaci.
• Potvrďte, že vygenerovaný seznam obsahuje 5–18 položek, používá logické pořadí a neobsahuje žádné položky H4 při aktuální konfiguraci.
• Potvrďte, že config/_default/markup.toml stále používá startLevel = 2, endLevel = 3 a ordered = false, nebo aktualizujte tuto specifikaci se změnou komponenty.
• Potvrďte, že stránka bez způsobilého H2 netvrdí, že obsahuje TOC; shortcode tiše nevykreslí nic.
• Potvrďte, že každý vygenerovaný fragment je jedinečný a dosahuje zamýšleného nadpisu.
• Otestujte publikované příchozí URL kotev před změnou jakéhokoli znění H2 nebo H3; zachovejte stará ID, když se nadpisy musí změnit.
• Na desktopu ověřte, že sticky obal je skrytý při 300 pixelech nebo méně a objeví se po překročení pozice rolování 300 pixelů.
• Ověřte, že pevný obal leží pod skutečnou hlavičkou, indikátor průběhu se posouvá a aktivní popisek sleduje změny sekcí.
• Ověřte, že úzké výřezy nezobrazují aktuální ovládací prvek, a zaznamenejte to jako očekávané současné chování, nikoli jako rozbitý snímek obrazovky.
• Zaznamenejte aktuální omezení přístupnosti: žádný navigační landmark, žádný klávesnicově zaměřitelný viditelný spouštěč, žádný přenos focusu, žádná aktualizace fragmentu a žádná větev pro omezený pohyb.
• Potvrďte, že žádná cesta snímku obrazovky není renderována, dokud odpovídající aktivum neexistuje na disku.

FAQ

Níže uvedené otázky pokrývají redakční rozhodnutí, která nejčastěji způsobují, že je tento prvek přidán příliš brzy, příliš hluboko nebo je po publikaci rozbitý.