Cuprins: Format și reguli

În biblioteca de elemente , o prezentare generală și un cuprins le spun cititorilor ce acoperă o pagină, ce îi va ajuta să decidă și cum să sară la secțiunea de care au nevoie.

Prezentare generală. Folosește acest element de deschidere pereche pe pagini lungi sau cu structură complexă. Scrie o prezentare generală de 40–90 de cuvinte care stabilește domeniul și rezultatul așteptat, apoi oferă o listă de conținut formată din titluri H2 stabile și doar titluri H3 utile. Pe acest site, controlul live al cuprinsului de mai jos rămâne ascuns până când cititorul a derulat mai mult de 300 de pixeli; apoi apare ca un meniu drop-down fix pe desktop sub antetul site-ului.

De ce contează acest element

Cititorii nu încep fiecare pagină lungă din același punct. O persoană are nevoie de o definiție, alta vrea pași de implementare, iar o a treia verifică o singură constrângere înainte de a aproba o lucrare. O scurtă prezentare generală răspunde la „Sunt în locul potrivit?” înainte ca cititorul să investească atenție. Lista de conținut răspunde la „Unde este partea de care am nevoie?” fără a forța o lectură liniară.

Cele două părți sunt specificate împreună pentru că rezolvă probleme de orientare adiacente, dar diferite. Prezentarea generală explică promisiunea, limitele și rezultatul util al paginii în propoziții. Lista de conținut expune ruta prin acea promisiune ca destinații. O listă de conținut fără o prezentare generală poate arăta că o pagină are secțiuni numite „Configurare” și „Accesibilitate”, dar nu poate explica dacă pagina este o introducere conceptuală sau o specificație de producție. O prezentare generală fără navigare poate stabili domeniul, dar tot face cititorul să caute prin 3.000 de cuvinte.

Acest element îmbunătățește și extractibilitatea automată, adică abilitatea software-ului de a izola un pasaj și de a-i reține scopul în afara paginii complete. Prezentarea generală este un al doilea rezumat concis și autonom după titlu și descriere. Cuprinsul sursă Hugo este o schiță legată și lizibilă automat a acoperirii și ierarhiei paginii; renderul lipicios curent convertește acele legături în opțiuni care își păstrează valorile fragmentelor URL, partea #secțiune a unui URL. Sistemele de căutare, instrumentele de regăsire, extensiile de browser și agenții AI pot folosi schița documentului pentru a identifica zonele probabile de răspuns înainte de a procesa fiecare paragraf. Acest lucru nu garantează o funcție de căutare sau o citare AI; reduce ambiguitatea despre unde încep subiectele și cum se relaționează.

Perechea nu trebuie să creeze repetiție. O prezentare generală stabilește domeniul și rezultatul. Un bloc de răspuns direct răspunde la întrebarea principală. Concluziile cheie enunță concluzii care merită reținute. Când toate trei spun același lucru în casete diferite, deschiderea devine un obstacol, nu un ajutor.

Când să îl folosești

Lista de conținut își justifică locul când săritul este un comportament probabil al cititorului. Numărul de cuvinte este un proxy util, dar structura este factorul decisiv.

Folosește doar prezentarea generală când titlul ar putea fi interpretat larg, când pagina exclude în mod deliberat subiecte adiacente sau când cititorul trebuie să cunoască rezultatul așteptat înainte de a continua. O pagină de politică de 900 de cuvinte poate avea nevoie de o prezentare generală de două propoziții chiar dacă nu are nevoie de navigare.

Folosește doar lista de conținut numai când titlul și deschiderea fac deja domeniul de neconfundat. Această situație este comună pe paginile de referință: deschiderea poate conține o definiție directă care îndeplinește rolul de orientare, în timp ce un set lung de câmpuri independente are totuși nevoie de navigare.

Nu folosi niciuna dintre părți ca ornament. Un TOC cu șase elemente pe un articol de 700 de cuvinte adaugă o decizie suplimentară înainte de răspuns. O prezentare generală care spune „Acest ghid explorează tot ce trebuie să știi” nu definește domeniul, rezultatul sau excluderile. Nu folosi perechea pentru a ascunde o structură slabă de titluri: dacă titlurile se suprapun, folosesc o gramatică inconsecventă sau împart o idee în multe secțiuni mici, repară documentul înainte de a-i expune schița.

Unde să îl plasezi

Poziția face parte din înțelesul elementului. Prezentarea generală trebuie să apară după hero sau răspunsul direct de deschidere și înainte de primul H2. Poate fi un paragraf scurt sau o listă compactă, dar trebuie întâlnită înainte ca cititorul să se angajeze în corpul textului. Invocarea TOC aparține imediat după prezentarea generală, astfel încât sursa redactată să păstreze orientarea și navigarea împreună, chiar dacă controlul lipicios al acestui site devine vizibil doar după derularea a 300 de pixeli.

Perechea nu poate întrerupe o definiție, nu poate separa o afirmație de dovezile sale și nu poate apărea pentru prima dată la jumătatea documentului. Nu o plasa între un titlu și paragraful de deschidere al acelui titlu: relația dintre titlu și explicație trebuie să rămână directă. Nu plasa alt component de tip prezentare generală imediat lângă ea. Când este necesar un bloc de răspuns direct sau de concluzii cheie, atribuie sarcini distincte și folosește această ordine: răspuns direct, prezentare generală scurtă a domeniului, invocare TOC, prima secțiune a corpului. Omite unul dintre rezumate dacă formularea se suprapune totuși.

Folosește shortcode-ul o dată pe pagină. ID-urile sale redate (tocDropdown, tocSelect, selectTrigger și controalele asociate) sunt fixe, așa că o a doua instanță creează ID-uri de document duplicate și scripturi imprevizibile.

Anatomie

Elementul are șase zone semnificative. Primele cinci sunt conținut sau comportament; indicatorul de progres este stare. Legenda este păstrată în pagină pentru a rămâne lizibilă când captura de ecran este redimensionată sau înlocuită.

1. Corpul prezentării generale: 40–90 de cuvinte care enunță domeniul, rezultatul intenționat și orice limită importantă.
2. Titlul wrapper-ului lipicios: titlul paginii în mod implicit, sau atributul title redactat când o etichetă mai scurtă este mai clară.
3. Eticheta secțiunii curente: începe ca „Selectează secțiunea…” și se schimbă pe măsură ce IntersectionObserver-ul browserului, o API care detectează elementele care intră într-o regiune definită a viewport-ului, marchează secțiunile ca active.
4. Triggerul drop-down-ului: deschide lista generată de destinații de secțiuni la click în implementarea curentă.
5. Opțiunile titlurilor: linkuri derivate din cuprinsul paginii Hugo, în prezent H2 și H3 datorită markup.toml.
6. Bara de progres: arată proporția din documentul derulabil total parcurs; nu identifică finalizarea secțiunii.

Exemple de design

Galeriacoperă stări de comportament, nu teme decorative. Conținutul de bază rămâne același, astfel încât reviewerii să poată compara sincronizarea, ierarhia, decuparea și interacțiunea.

Nu sunt redactate variante vizuale alternative prin Markdown. title schimbă eticheta și class adaugă clase wrapper, dar niciuna nu creează un element semantic diferit. Tratamente noi de culoare, card, sidebar sau listă inline necesită o decizie de componentă, nu o clasă arbitrară adăugată în conținut.

Parametri

Prezentarea generală și TOC împart un singur contract editorial, dar doar TOC-ul lipicios este redat de shortcode-ul curent. Valorile de configurare sunt incluse pentru că schimbă rezultatul, chiar dacă autorii nu le pot seta per invocare.

Dependența este ușor de ratat: o pagină fără titluri H2 nu redă silențios niciun TOC lipicios, deoarece Hugo nu produce nicio schiță utilizabilă, iar parțialul emite markup doar când are anteturi. Cu configurația curentă, H2 și descendenții lor H3 sunt eligibili; H4 și titlurile mai profunde sunt excluse. Parțialul analizează în mod normal .TableOfContents al lui Hugo. Rezerva sa HTML scanează doar elementele H2 redate, așa că autorii nu trebuie să se bazeze pe comportamentul de rezervă pentru a păstra navigarea H3.

Sintaxă și exemple de cod

Notația portabilă păstrează prezentarea generală ca corp al elementului și setările de navigare ca atribute. Linkurile titlurilor rămân generate din documentul înconjurător, nu duplicate de autor.

:::quick-overview-and-toc{title="Pe această pagină" class=""}
Acest ghid explică când să folosești elementul, cum se comportă controlul lipicios Hugo
și cum să păstrezi destinații de secțiuni accesibile și stabile după publicare.
:::

Maparea Hugo curentă scrie prezentarea generală ca Markdown normal și invocă shortcode-ul livrat o dată. Nu există corp JSON.

Acest ghid explică când să folosești elementul, cum se comportă controlul lipicios Hugo
și cum să păstrezi destinații de secțiuni accesibile și stabile după publicare.

{{< table-of-contents title="Pe această pagină" class="" >}}

Maparea blocului WordPress păstrează același corp și atribute. Un site care nu a înregistrat blocul poate folosi forma echivalentă de shortcode; nu trebuie să scrie manual linkurile titlurilor.

<!-- wp:amicited/quick-overview-and-toc {"title":"Pe această pagină","className":""} -->
<p>Acest ghid explică când să folosești elementul, cum se comportă controlul lipicios
și cum să păstrezi destinații de secțiuni accesibile și stabile după publicare.</p>
<!-- /wp:amicited/quick-overview-and-toc -->

[amicited_quick_overview_toc title="Pe această pagină" class=""]
Acest ghid explică domeniul, comportamentul și politica de ancoră a elementului.
[/amicited_quick_overview_toc]

În toate cele trei sisteme, sursa de adevăr este ierarhia reală a titlurilor documentului. O listă întreținută manual se va îndepărta pe măsură ce titlurile se schimbă și poate indica ID-uri care nu mai sunt prezente.

Exemple

Exemplu bun

Prezentare generală. Acest ghid arată echipelor de conținut cum să planifice, să scrie, să revizuiască și să întrețină o pagină de comparație. Acoperă standarde de dovezi, criterii de comparație, afirmații despre produse, tabele accesibile și verificări post-publicare. Nu acoperă plasarea plătită sau termenii comisioanelor de afiliere.

Pe această pagină: Definește decizia · Selectează criterii de comparație · Adună dovezi · Redactează pagina · Revizuiește afirmațiile · Măsoară și întreține

Acest exemplu funcționează deoarece prezentarea generală numește publicul, rezultatul, acoperirea și limita în 48 de cuvinte. Cele șase destinații sunt sarcini distincte pe care un cititor le poate revedea independent. Etichetele lor folosesc fraze verbale paralele, astfel încât atât oamenii, cât și mașinile pot deduce un proces. Nicio intrare nu repetă titlul paginii și nu expune o subsecțiune trivială.

Exemplu rău

Prezentare generală: Bun venit la ghidul nostru complet. În lumea în schimbare de astăzi, există multe de știut, așa că citește mai departe pentru a afla totul.

Conținut: Introducere · Mai multe informații · Lucruri importante · Alte lucruri · Concluzie

Acest exemplu eșuează din două motive. Prezentarea generală consumă 22 de cuvinte fără a defini domeniul, cititorul, rezultatul sau excluderea. Intrările etichetează containere retorice în loc de subiecte, așa că nu ajută un cititor să prezică unde se află un răspuns. Adăugarea mai multor titluri nu l-ar rezolva; documentul are nevoie mai întâi de limite de secțiune semnificative.

O a doua situație apropiată este un răspuns de 600 de cuvinte cu „Prezentare generală,” „Context,” „Detalii,” „Sfaturi” și „Concluzie” în TOC-ul său. Chiar dacă fiecare ancoră funcționează, lista adaugă mai multă interfață decât valoare de navigare. Păstrează deschiderea directă și elimină TOC-ul.

Marcaj schema și accesibilitate

Aici, marcaj schema înseamnă cod standardizat lizibil automat care identifică entități și proprietăți. Acest element nu are un tip sau o proprietate dedicată în vocabularul Schema.org, iar shortcode-ul Hugo nu emite JSON-LD, notația bazată pe script folosită în mod obișnuit pentru a publica acel vocabular. Nu marca TOC-ul ca ItemList doar pentru că este o listă; asta ar sugera o listă de elemente de subiect, nu de navigare. Prezentarea generală poate informa description-ul unei pagini doar când formularea este independent potrivită, dar nu este copiată automat în datele structurate.

Comportamentul HTML și ARIA contează mai mult aici. ARIA, standardul pentru aplicații internet bogate accesibile, oferă roluri, nume și stări atunci când HTML-ul nativ nu o face. Un reper este o regiune numită a paginii la care utilizatorii de tehnologii asistive pot sări. Focusul este ținta curentă de interacțiune prin tastatură.

Acestea sunt fapte de implementare, nu permisiunea de a ignora accesibilitatea. Reviewerii de conținut pot verifica claritatea titlurilor, ID-urile unice și ordinea logică de azi. Proprietarii de componente trebuie să rezolve comportamentul triggerului, reperului, focusului, URL-ului și mișcării reduse înainte de a descrie varianta lipicioasă ca fiind accesibilă prin tastatură.

Reguli de redactare

Scrie prezentarea generală după ce structura paginii este stabilă. Acest lucru previne ca o promisiune timpurie să se îndepărteze de acoperirea finalizată. Păstreaz-o între 40 și 90 de cuvinte. Preferă două sau trei propoziții; folosește trei până la cinci puncte doar când pagina conține câteva rezultate cu adevărat paralele. Enunță ce ajută pagina cititorul să înțeleagă, să decidă sau să facă. Numește o excludere când titlul ar putea promite în mod rezonabil mai mult decât livrează pagina.

Folosește H2 pentru întrebările, etapele sau zonele de decizie majore ale paginii. Include H3 în navigare doar când este o destinație independentă utilă sub un H2 substanțial. Pe acest site, configurația include automat fiecare H2 și H3, așa că politica practică este mai strictă: nu crea un titlu decât dacă merită să apară în navigare. Țintește 5–18 intrări totale. Dacă lista generată depășește 18, combină secțiunile suprapuse, elimină titlurile H3 inutile sau împarte pagina. Nu sări niciodată direct de la H2 la H4 pentru a ascunde un titlu de la TOC; nivelurile de titlu exprimă ierarhie, nu preferințe de stil sau navigare.

Folosește text de titlu concis și descriptiv. Un cititor ar trebui să înțeleagă fiecare destinație fără a citi paragraful părinte. Preferă forme paralele într-o secvență: „Alege criterii,” „Adună dovezi” și „Revizuiește afirmațiile” sunt mai ușor de scanat decât un amestec de substantive, întrebări și etichete vagi. Nu pune citări, afirmații promoționale, emoji-uri, insigne de stare sau propoziții complete într-un titlu doar pentru a influența TOC-ul.

Prezentarea generală nu trebuie să conțină niciodată o a doua listă de conținut miniaturală, afirmații de performanță nesuportate sau instrucțiuni care nu apar nicăieri în corp. TOC-ul nu trebuie să conțină niciodată ancore tastate manual, destinații în afara paginii curente sau linkuri către secțiuni goale.

Politica de stabilitate a ancorelor

Un ID de titlu este partea de fragment a unui URL, cum ar fi #politica-de-stabilitate-a-ancorelor. URL-urile de fragment publicate sunt interfețe publice. Marcaje, linkuri de campanie, documentație de suport, rezultate de căutare și răspunsuri generate de AI pot indica direct către ele. Schimbarea textului titlului poate schimba ID-ul generat de Hugo și poate distruge fiecare ancoră de intrare chiar și atunci când URL-ul paginii rămâne același.

După publicare, îngheață ID-urile tuturor titlurilor H2 și H3. Preferă editarea paragrafului de sub un titlu în locul redenumirii titlului. Când o redenumire este necesară, păstrează vechiul ID printr-un mecanism de ancoră explicită suportat de sistemul de publicare, apoi verifică atât fragmentul vechi de intrare, cât și noua selecție TOC. Nu refolosi niciodată un ID vechi pentru un subiect diferit, nu duplica niciodată un ID pe pagină și nu traduce niciodată un ID pe un URL localizat existent fără un plan de migrare. Înregistrează modificările intenționate de ancoră în nota de lansare sau în jurnalul de modificări de conținut, astfel încât proprietarii linkurilor de intrare cunoscute să le poată actualiza.

Tipuri de postări care îl folosesc

Frontmatter-ul postTypes listează formatele pentru care acest element face parte din modelul de producție. Este totuși condiționat: o instanță scurtă a unui format în mod normal lung poate să nu îndeplinească pragul TOC.

Paginile de produs, categorie și caz de utilizare nu sunt incluse în mod implicit, deoarece călătoriile lor principale sunt adesea gestionate de navigarea la nivel de pagină și call-to-action. Adaugă acest element doar printr-o decizie documentată de șablon, nu pentru că pagina se întâmplă să fie lungă.

Lista de verificare QA

• Confirmă că pagina îndeplinește pragul: cel puțin 1.800 de cuvinte, șapte secțiuni H2 sau o nevoie documentată de navigare neliniară.
• Confirmă că prezentarea generală are 40–90 de cuvinte și enunță domeniul, rezultatul intenționat și orice excludere necesară.
• Confirmă că prezentarea generală nu repetă răspunsul direct sau concluziile cheie.
• Confirmă că shortcode-ul apare o dată, imediat după prezentarea generală și înainte de primul H2.
• Confirmă că fiecare H2 este o destinație majoră semnificativă și fiecare H3 este suficient de util pentru a apărea în navigare.
• Confirmă că lista generată conține 5–18 intrări, folosește o ordine logică și nu conține elemente H4 sub configurația curentă.
• Confirmă că config/_default/markup.toml încă folosește startLevel = 2, endLevel = 3 și ordered = false, sau actualizează această specificație cu modificarea componentei.
• Confirmă că o pagină fără H2 eligibil nu pretinde că conține un TOC; shortcode-ul nu va reda nimic în tăcere.
• Confirmă că fiecare fragment generat este unic și ajunge la titlul intenționat.
• Testează URL-urile de ancoră publicate înainte de a schimba formularea vreunui H2 sau H3; păstrează ID-urile vechi când titlurile trebuie modificate.
• Pe desktop, verifică că wrapper-ul lipicios este ascuns la 300 de pixeli sau mai puțin și apare după ce poziția de derulare depășește 300 de pixeli.
• Verifică că wrapper-ul fix se află sub antetul efectiv, bara de progres avansează și eticheta activă urmărește schimbările de secțiune.
• Verifică că viewporturile înguste nu afișează controlul curent și înregistrează aceasta ca un comportament curent așteptat, nu ca o captură de ecran defectă.
• Înregistrează limitările curente de accesibilitate: niciun reper de navigare, niciun trigger vizibil focusabil prin tastatură, nicio transferare de focus, nicio actualizare de fragment și nicio ramură de mișcare redusă.
• Confirmă că nicio cale de captură de ecran nu este redată până când activul corespunzător există pe disc.

FAQ

Întrebările de mai jos acoperă deciziile editoriale care cauzează cel mai adesea ca acest element să fie adăugat prea devreme, făcut prea adânc sau stricat după publicare.