Obsah: Formát a pravidlá

V knižnici prvkov rýchly prehľad a obsah hovoria čitateľom, čo stránka pokrýva, s čím im pomôže rozhodnúť sa a ako preskočiť na sekciu, ktorú potrebujú.

Rýchly prehľad. Použite tento párový úvodný prvok na dlhých alebo štruktúrne zložitých stránkach. Napíšte prehľad v rozsahu 40 – 90 slov, ktorý stanoví rozsah a očakávaný výsledok, potom poskytnite zoznam obsahu vytvorený zo stabilných nadpisov H2 a len užitočných nadpisov H3. Na tejto stránke zostáva ovládací prvok obsahu skrytý, kým čitateľ neposunie stránku o viac ako 300 pixelov; potom sa zobrazí ako fixný rozbaľovací zoznam na desktopovej verzii pod záhlavím stránky.

Prečo na tomto prvku záleží

Čitatelia nezačínajú každú dlhú stránku v rovnakom bode. Jeden potrebuje definíciu, iný chce implementačné kroky a tretí kontroluje jediné obmedzenie pred schválením práce. Krátky prehľad odpovedá na otázku „Som na správnom mieste?“ skôr, než čitateľ investuje pozornosť. Zoznam obsahu odpovedá na otázku „Kde je časť, ktorú potrebujem?“ bez toho, aby nútil k lineárnemu čítaniu.

Obe časti sú špecifikované spoločne, pretože riešia susediace, ale odlišné orientačné problémy. Prehľad vysvetľuje prísľub stránky, jej hranice a užitočný výsledok vo vetách. Zoznam obsahu odhaľuje cestu k tomuto prísľubu ako ciele. Zoznam obsahu bez prehľadu môže ukázať, že stránka má sekcie s názvom „Konfigurácia“ a „Prístupnosť“, ale nedokáže vysvetliť, či je stránka koncepčným úvodom alebo produkčnou špecifikáciou. Prehľad bez navigácie môže stanoviť rozsah, ale aj tak prinúti čitateľa prehľadávať 3 000 slov.

Tento prvok tiež zlepšuje strojovú extrahovateľnosť, teda schopnosť softvéru izolovať pasáž a zachovať jej účel mimo celej stránky. Prehľad je druhým stručným, sebestačným súhrnom po nadpise a popise. Zdrojový obsah Hugo je prepojený, strojovo čitateľný prehľad pokrytia a hierarchie stránky; aktuálny fixný renderer konvertuje tieto odkazy na možnosti, ktoré si zachovávajú hodnoty URL fragmentov, časť #sekcia URL. Vyhľadávacie systémy, nástroje na vyhľadávanie, prehliadačové rozšírenia a AI agenti môžu použiť prehľad dokumentu na identifikáciu pravdepodobných oblastí s odpoveďami pred spracovaním každého odseku. Toto nezaručuje vyhľadávaciu funkciu alebo AI citáciu; znižuje nejednoznačnosť ohľadom toho, kde sa témy začínajú a ako spolu súvisia.

Toto párovanie nesmie vytvárať opakovanie. Prehľad uvádza rozsah a výsledok. Blok s priamou odpoveďou odpovedá na primárnu otázku. Kľúčové poznatky uvádzajú závery, ktoré stoja za zapamätanie. Keď všetky tri hovoria to isté v rôznych boxoch, úvod sa stáva prekážkou, nie pomocou.

Kedy ho použiť

Zoznam obsahu si zaslúži svoje miesto, keď je preskakovanie pravdepodobným správaním čitateľa. Počet slov je užitočným približným ukazovateľom, ale rozhodujúca je štruktúra.

Použite samostatný prehľad, keď by sa nadpis dal interpretovať široko, keď stránka zámerne vylučuje susediace témy, alebo keď čitateľ potrebuje poznať očakávaný výsledok pred pokračovaním. 900-slovná politická stránka môže potrebovať dvojvetný prehľad, aj keď nepotrebuje navigáciu.

Použite samostatný zoznam obsahu len vtedy, keď nadpis a úvod už robia rozsah nepochybným. Táto hraničná situácia je bežná na referenčných stránkach: úvod môže obsahovať priamu definíciu, ktorá plní orientačnú úlohu, zatiaľ čo dlhá sada nezávislých polí stále potrebuje navigáciu.

Nepoužívajte ani jednu časť ako dekoráciu. Šesťpoložkový TOC na 700-slovnom článku pridáva ďalšie rozhodnutie pred odpoveďou. Prehľad, ktorý hovorí „Tento sprievodca preskúma všetko, čo potrebujete vedieť“, nedefinuje rozsah, výsledok ani vylúčenia. Nepoužívajte túto dvojicu na zakrytie slabej štruktúry nadpisov: ak sa nadpisy prekrývajú, používajú nekonzistentnú gramatiku alebo rozdeľujú jednu myšlienku na mnoho malých sekcií, opravte dokument skôr, než zverejníte jeho prehľad.

Kde ho umiestniť

Umiestnenie je súčasťou významu prvku. Prehľad musí byť uvedený za hrdinom stránky alebo úvodnou priamou odpoveďou a pred prvým H2. Môže ísť o krátky odsek alebo kompaktný zoznam, ale čitateľ sa s ním musí stretnúť predtým, než sa ponorí do tela stránky. Volanie TOC patrí bezprostredne za prehľad, aby autorský zdroj udržal orientáciu a navigáciu pohromade, aj keď sa fixný ovládací prvok tejto stránky stáva viditeľným až po posunutí o 300 pixelov.

Dvojica nesmie prerušiť definíciu, oddeliť tvrdenie od jeho dôkazu ani sa objaviť prvýkrát uprostred dokumentu. Neumiestňujte ju medzi nadpis a jeho úvodný odsek: vzťah medzi nadpisom a vysvetlením by mal zostať priamy. Neumiestňujte iný komponent typu prehľad priamo vedľa neho. Ak sa vyžaduje blok s priamou odpoveďou alebo kľúčové poznatky, prideľte im odlišné úlohy a použite toto poradie: priama odpoveď, krátky prehľad rozsahu, volanie TOC, prvá hlavná sekcia. Vynechajte jeden zo súhrnov, ak sa znenie stále prekrýva.

Použite shortcode raz na stránku. Jeho vykreslené ID (tocDropdown, tocSelect, selectTrigger a súvisiace ovládacie prvky) sú pevné, takže druhá inštancia vytvára duplicitné ID dokumentu a nepredvídateľné skripty.

Anatómia

Prvok má šesť významných oblastí. Prvých päť je obsah alebo správanie; indikátor priebehu je stav. Legenda je ponechaná na stránke, aby zostala čitateľná pri zmene veľkosti alebo výmene snímky obrazovky.

1. Telo prehľadu: 40 – 90 slov uvádzajúcich rozsah, zamýšľaný výsledok a akékoľvek dôležité hranice.
2. Názov fixného obalu: predvolene názov stránky alebo autorom zadaný atribút title, ak je kratší názov jasnejší.
3. Označenie aktuálnej sekcie: začína ako „Vyberte sekciu…“ a mení sa, keď prehliadačov IntersectionObserver, API, ktoré deteguje vstup prvkov do definovanej oblasti zobrazenia, označí sekcie ako aktívne.
4. Rozbaľovacie tlačidlo: po kliknutí otvorí vygenerovaný zoznam cieľov sekcií v aktuálnej implementácii.
5. Možnosti nadpisov: odkazy odvodené z obsahu Hugo stránky, aktuálne H2 a H3 kvôli markup.toml.
6. Lišta priebehu: zobrazuje podiel celkového posúvateľného dokumentu, ktorý bol prejdený; neidentifikuje dokončenie sekcií.

Príklady dizajnu

Galéria pokrýva stavy správania, nie dekoratívne témy. Základný obsah zostáva rovnaký, aby recenzenti mohli porovnávať načasovanie, hierarchiu, orezávanie a interakciu.

Žiadne alternatívne vizuálne varianty nie sú vytvárané prostredníctvom Markdown. title mení názov a class pridáva triedy obalu, ale ani jedno nevytvára sémanticky odlišný prvok. Nové farebné, kartové, bočné alebo inline-zoznamové úpravy vyžadujú rozhodnutie komponentu, nie ľubovoľnú triedu pridanú v obsahu.

Parametre

Prehľad a TOC zdieľajú jednu redakčnú dohodu, ale iba fixný TOC je vykresľovaný aktuálnym shortcode. Konfiguračné hodnoty sú zahrnuté, pretože menia výstup, aj keď ich autori nemôžu nastaviť pri každom volaní.

Závislosť je ľahké prehliadnuť: stránka bez nadpisov H2 ticho nevykreslí žiadny fixný TOC, pretože Hugo nevytvorí použiteľný prehľad a partial vypúšťa značky len vtedy, keď má hlavičky. Pri aktuálnej konfigurácii sú vhodné H2 a ich H3 potomkovia; H4 a hlbšie nadpisy sú vylúčené. Partial normálne parsuje Hugo .TableOfContents. Jeho HTML fallback skenuje len vykreslené H2 prvky, takže autori sa nesmú spoliehať na fallback správanie na zachovanie navigácie H3.

Syntax a príklady kódu

Prenosná notácia ponecháva prehľad ako telo prvku a navigačné nastavenia ako atribúty. Odkazy na nadpisy zostávajú generované z okolitého dokumentu, nie duplikované autorom.

:::quick-overview-and-toc{title="On this page" class=""}
Tento sprievodca vysvetľuje, kedy prvok použiť, ako sa správa fixný Hugo ovládací prvok
a ako zachovať prístupné, stabilné ciele sekcií po publikovaní.
:::

Aktuálne Hugo mapovanie zapíše prehľad ako bežný Markdown a raz zavolá dodaný shortcode. Neexistuje žiadne JSON telo.

Tento sprievodca vysvetľuje, kedy prvok použiť, ako sa správa fixný Hugo ovládací prvok
a ako zachovať prístupné, stabilné ciele sekcií po publikovaní.

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

WordPress blokové mapovanie ukladá rovnaké telo a atribúty. Stránka, ktorá nezaregistrovala blok, môže použiť ekvivalentnú shortcode formu; nesmie ručne vytvárať odkazy na nadpisy.

<!-- wp:amicited/quick-overview-and-toc {"title":"On this page","className":""} -->
<p>Tento sprievodca vysvetľuje, kedy prvok použiť, ako sa správa fixný ovládací prvok
a ako zachovať prístupné, stabilné ciele sekcií po publikovaní.</p>
<!-- /wp:amicited/quick-overview-and-toc -->

[amicited_quick_overview_toc title="On this page" class=""]
Tento sprievodca vysvetľuje rozsah prvku, správanie a politiku kotiev.
[/amicited_quick_overview_toc]

Vo všetkých troch systémoch je zdrojom pravdy skutočná hierarchia nadpisov dokumentu. Ručne udržiavaný zoznam sa bude časom rozchádzať so zmenami nadpisov a môže ukazovať na ID, ktoré už neexistujú.

Príklady

Dobrý príklad

Rýchly prehľad. Tento sprievodca ukazuje obsahovým tímom, ako plánovať, písať, recenzovať a udržiavať porovnávaciu stránku. Pokrýva štandardy dôkazov, porovnávacie kritériá, produktové tvrdenia, prístupné tabuľky a kontroly po publikovaní. Nepokrýva platené umiestnenie ani podmienky affiliate provízií.

Na tejto stránke: Definujte rozhodnutie · Vyberte porovnávacie kritériá · Zhromaždite dôkazy · Napíšte stránku · Skontrolujte tvrdenia · Merajte a udržiavajte

Toto funguje, pretože prehľad v 48 slovách pomenúva publikum, výsledok, pokrytie a hranice. Šesť cieľov sú odlišné úlohy, ktoré môže čitateľ znovu navštevovať nezávisle. Ich názvy používajú paralelné slovesné frázy, takže ľudia aj stroje dokážu odvodiť proces. Žiadna z položiek neopakuje názov stránky ani neodhaľuje triviálnu podsekciu.

Zlý príklad

Prehľad: Vitajte v našom kompletnom sprievodcovi. V dnešnom meniacom sa svete je veľa toho, čo treba vedieť, takže čítajte ďalej a dozviete sa všetko.

Obsah: Úvod · Viac informácií · Dôležité veci · Iné veci · Záver

Toto zlyháva z dvoch dôvodov. Prehľad míňa 22 slov bez definovania rozsahu, čitateľa, výsledku alebo vylúčenia. Položky označujú rétorické kontajnery, nie témy, takže nepomáhajú čitateľovi predpovedať, kde žije odpoveď. Pridanie ďalších nadpisov by to nevyriešilo; dokument najprv potrebuje zmysluplné hranice sekcií.

Druhý hraničný prípad je 600-slovná odpoveď s „Prehľad“, „Pozadie“, „Detaily“, „Tipy“ a „Záver“ v jej TOC. Aj keď každá kotva funguje, zoznam pridáva viac rozhrania ako navigačnej hodnoty. Ponechajte priamy úvod a odstráňte TOC.

Schema markup a prístupnosť

Tu schema markup znamená štandardizovaný strojovo čitateľný kód, ktorý identifikuje entity a vlastnosti. Tento prvok nemá v slovnej zásobe Schema.org žiadny vyhradený typ alebo vlastnosť a Hugo shortcode nevysiela JSON-LD, notáciu založenú na skriptoch bežne používanú na publikovanie tejto slovnej zásoby. Neoznačujte TOC ako ItemList len preto, že je to zoznam; to by naznačovalo zoznam tematických položiek, nie navigáciu. Prehľad môže informovať description stránky len vtedy, keď je znenie samostatne vhodné, ale nie je automaticky kopírované do štruktúrovaných údajov.

HTML a ARIA správanie sú tu dôležitejšie. ARIA, štandard pre prístupné internetové aplikácie, poskytuje roly, názvy a stavy tam, kde natívne HTML nestačí. Landmark je pomenovaná oblasť stránky, na ktorú môžu používatelia asistenčných technológií preskočiť. Focus je aktuálny cieľ klávesovej interakcie.

Toto sú implementačné fakty, nie povolenie ignorovať prístupnosť. Recenzenti obsahu môžu overiť jasnosť nadpisov, jedinečné ID a logické poradie už dnes. Vlastníci komponentov musia vyriešiť správanie spúšťača, landmarku, focusu, URL a zníženého pohybu predtým, než budú fixný variant popisovať ako klávesovo prístupný.

Pravidlá písania

Napíšte prehľad až po stabilizácii štruktúry stránky. Tým sa zabráni tomu, aby sa skorý prísľub odchýlil od hotového pokrytia. Udržujte ho medzi 40 a 90 slovami. Uprednostnite dve alebo tri vety; použite tri až päť odrážok len vtedy, keď stránka obsahuje niekoľko skutočne paralelných výsledkov. Uveďte, čo stránka pomáha čitateľovi pochopiť, rozhodnúť alebo urobiť. Pomenujte vylúčenie, keď by nadpis mohol rozumne sľubovať viac, než stránka poskytuje.

Použite H2 pre hlavné otázky, fázy alebo rozhodovacie oblasti stránky. Zahrňte H3 do navigácie len vtedy, keď ide o užitočný nezávislý cieľ v rámci rozsiahlej H2. Na tejto stránke konfigurácia automaticky zahŕňa každý H2 a H3, takže praktická politika je prísnejšia: nevytvárajte nadpis, pokiaľ si nezaslúži byť v navigácii. Cieľom je 5 – 18 celkových položiek. Ak vygenerovaný zoznam presahuje 18, skombinujte prekrývajúce sa sekcie, odstráňte nepotrebné H3 nadpisy alebo stránku rozdeľte. Nikdy neskáčte priamo z H2 na H4, aby ste skryli nadpis z TOC; úrovne nadpisov vyjadrujú hierarchiu, nie štýlovanie alebo preferenciu navigácie.

Používajte stručný, popisný text nadpisov. Čitateľ by mal pochopiť každý cieľ bez čítania jeho nadradeného odseku. Uprednostnite paralelné formy v rámci sekvencie: „Vyberte kritériá“, „Zhromaždite dôkazy“ a „Skontrolujte tvrdenia“ sa ľahšie skenujú ako zmes podstatných mien, otázok a vágnych názvov. Nevkladajte citácie, propagačné tvrdenia, emotikony, stavové odznaky ani celé vety do nadpisu len kvôli ovplyvneniu TOC.

Prehľad nesmie nikdy obsahovať druhý miniatúrny zoznam obsahu, nepodložené tvrdenia o výkone ani inštrukcie, ktoré sa nikde v tele nevyskytujú. TOC nesmie nikdy obsahovať ručne písané kotvy, ciele mimo aktuálnej stránky ani odkazy na prázdne sekcie.

Politika stability kotiev

ID nadpisu je fragmentová časť URL, napríklad #anchor-stability-policy. Publikované fragmentové URL sú verejné rozhrania. Záložky, kampane, podporná dokumentácia, výsledky vyhľadávania a AI-generované odpovede môžu na ne priamo odkazovať. Zmena textu nadpisu môže zmeniť Hugo-generované ID a zlomiť každú prichádzajúcu kotvu, aj keď URL stránky zostane rovnaká.

Po publikovaní zmrazte ID všetkých nadpisov H2 a H3. Uprednostnite úpravu odseku pod nadpisom pred premenovaním nadpisu. Keď je premenovanie nevyhnutné, zachovajte staré ID pomocou mechanizmu explicitných kotiev podporovaného publikačným systémom, potom overte starý prichádzajúci fragment aj nový výber v TOC. Nikdy znovu nepoužívajte staré ID pre inú tému, nikdy neduplikujte ID na stránke a nikdy neprekladajte ID na existujúcej lokalizovanej URL bez migračného plánu. Zaznamenajte zámerné zmeny kotiev v poznámkach k vydaniu alebo v denníku zmien obsahu, aby ich vlastníci známych prichádzajúcich odkazov mohli aktualizovať.

Typy príspevkov, ktoré ho používajú

Frontmatter postTypes uvádza formáty, pre ktoré je tento prvok súčasťou produkčného vzoru. Je stále podmienečný: krátka inštancia normálne dlhého formátu môže byť pod hranicou TOC.

Produktové, kategóriové a prípadové stránky nie sú štandardne zahrnuté, pretože ich primárne cesty sú často riešené navigáciou na úrovni stránky a výzvami na akciu. Pridajte tento prvok len na základe zdokumentovaného rozhodnutia šablóny, nie preto, že je stránka náhodou dlhá.

Kontrolný zoznam QA

• Potvrďte, že stránka spĺňa hranicu: aspoň 1 800 slov, sedem sekcií H2 alebo zdokumentovaná potreba nelineárnej navigácie.
• Potvrďte, že prehľad má 40 – 90 slov a uvádza rozsah, zamýšľaný výsledok a všetky potrebné vylúčenia.
• Potvrďte, že prehľad neopakuje priamu odpoveď ani kľúčové poznatky.
• Potvrďte, že shortcode sa objaví raz, bezprostredne za prehľadom a pred prvým H2.
• Potvrďte, že každý H2 je zmysluplný hlavný cieľ a každý H3 je dostatočne užitočný na to, aby sa objavil v navigácii.
• Potvrďte, že vygenerovaný zoznam obsahuje 5 – 18 položiek, používa logické poradie a neobsahuje H4 položky pri aktuálnej konfigurácii.
• Potvrďte, že config/_default/markup.toml stále používa startLevel = 2, endLevel = 3 a ordered = false, alebo aktualizujte túto špecifikáciu so zmenou komponentu.
• Potvrďte, že stránka bez vhodných H2 netvrdí, že obsahuje TOC; shortcode ticho nevykreslí nič.
• Potvrďte, že každý vygenerovaný fragment je jedinečný a vedie k zamýšľanému nadpisu.
• Otestujte publikované prichádzajúce URL kotiev pred zmenou znenia akéhokoľvek H2 alebo H3; zachovajte staré ID, keď sa nadpisy musia zmeniť.
• Na desktope overte, že fixný obal je skrytý pri 300 pixeloch alebo menej a objaví sa po posunutí pozície nad 300 pixelov.
• Overte, že fixný obal je pod skutočným záhlavím, lišta priebehu sa posúva a aktívny názov nasleduje zmeny sekcií.
• Overte, že úzke zobrazenia nezobrazujú aktuálny ovládací prvok a zaznamenajte to ako očakávané aktuálne správanie, nie ako chybnú snímku obrazovky.
• Zaznamenajte aktuálne obmedzenia prístupnosti: žiadny navigačný landmark, žiadny klávesovo zamerateľný viditeľný spúšťač, žiadny presun focusu, žiadna aktualizácia fragmentu a žiadna vetva pre znížený pohyb.
• Potvrďte, že žiadna cesta k snímke obrazovky nie je vykreslená, kým na disku neexistuje zodpovedajúci súbor.

FAQ

Nižšie uvedené otázky pokrývajú redakčné rozhodnutia, ktoré najčastejšie spôsobujú, že tento prvok je pridaný príliš skoro, príliš hlboký alebo rozbitý po publikovaní.