Indice dei contenuti: formato e regole

Nella libreria degli elementi , una panoramica rapida e un indice dei contenuti dicono ai lettori cosa copre una pagina, cosa li aiuterà a decidere e come saltare alla sezione di cui hanno bisogno.

Panoramica rapida. Utilizza questo elemento di apertura abbinato su pagine lunghe o strutturalmente complesse. Scrivi una panoramica di 40–90 parole che definisca la portata e il risultato atteso, poi fornisci un elenco dei contenuti composto da intestazioni H2 stabili e solo dalle intestazioni H3 utili. Su questo sito, il controllo live dei contenuti qui sotto rimane nascosto fino a quando il lettore non ha scorretto oltre 300 pixel; appare poi come un menu a tendina fisso per desktop sotto l’intestazione del sito.

Perché questo elemento è importante

I lettori non iniziano ogni pagina lunga dallo stesso punto. Una persona ha bisogno di una definizione, un’altra vuole i passaggi di implementazione e una terza sta controllando un singolo vincolo prima di approvare il lavoro. Una breve panoramica risponde alla domanda “Sono nel posto giusto?” prima che il lettore investa attenzione. L’elenco dei contenuti risponde a “Dov’è la parte che mi serve?” senza forzare una lettura lineare.

Le due parti sono specificate insieme perché risolvono problemi di orientamento adiacenti ma diversi. La panoramica spiega la promessa, i confini e il risultato utile della pagina in frasi. L’elenco dei contenuti espone il percorso attraverso quella promessa come destinazioni. Un elenco dei contenuti senza panoramica può mostrare che una pagina ha sezioni chiamate “Configurazione” e “Accessibilità” ma non può spiegare se la pagina è un’introduzione concettuale o una specifica di produzione. Una panoramica senza navigazione può stabilire la portata ma costringere comunque un lettore a cercare tra 3.000 parole.

Questo elemento migliora anche l’estraibilità automatica, ovvero la capacità del software di isolare un passaggio e mantenerne lo scopo al di fuori della pagina completa. La panoramica è un secondo riepilogo conciso e autonomo dopo il titolo e la descrizione. L’indice dei contenuti sorgente di Hugo è una struttura collegata e leggibile dalla macchina della copertura e della gerarchia della pagina; il renderizzatore adesivo corrente converte quei collegamenti in opzioni che mantengono i loro valori di frammento URL, la parte #sezione di un URL. I sistemi di ricerca, gli strumenti di recupero, le estensioni del browser e gli agenti AI possono utilizzare la struttura del documento per identificare le probabili aree di risposta prima di elaborare ogni paragrafo. Questo non garantisce una funzione di ricerca o una citazione AI; riduce l’ambiguità su dove iniziano gli argomenti e come si relazionano.

L’abbinamento non deve creare ripetizioni. Una panoramica dichiara portata e risultato. Un blocco di risposta diretta risponde alla domanda principale. I punti chiave dichiarano le conclusioni che vale la pena ricordare. Quando tutti e tre dicono la stessa cosa in riquadri diversi, l’apertura diventa un ostacolo anziché un aiuto.

Quando usarlo

L’elenco dei contenuti si guadagna il suo posto quando saltare è un comportamento probabile del lettore. Il conteggio delle parole è un indicatore utile, ma la struttura è il fattore decisivo.

Usa solo la panoramica quando il titolo potrebbe essere interpretato in modo ampio, quando la pagina esclude deliberatamente argomenti adiacenti, o quando il lettore ha bisogno di conoscere il risultato atteso prima di procedere. Una pagina di policy di 900 parole può aver bisogno di una panoramica di due frasi anche se non necessita di navigazione.

Usa solo l’elenco dei contenuti unicamente quando il titolo e l’apertura rendono già inequivocabile la portata. Questo caso è comune nelle pagine di riferimento: l’apertura può contenere una definizione diretta che svolge il compito di orientamento, mentre un lungo insieme di campi indipendenti necessita comunque di navigazione.

Non usare nessuna delle due parti come decorazione. Un TOC di sei elementi in un articolo di 700 parole aggiunge una decisione extra prima della risposta. Una panoramica che dice “Questa guida esplora tutto ciò che devi sapere” non definisce portata, risultato o esclusioni. Non usare la coppia per nascondere una struttura di intestazioni debole: se le intestazioni si sovrappongono, usano una grammatica incoerente o dividono un’idea in molte sezioni minuscole, correggi prima il documento prima di esporne la struttura.

Dove posizionarlo

La posizione è parte del significato dell’elemento. La panoramica deve apparire dopo l’hero o la risposta diretta di apertura e prima della prima H2. Può essere un breve paragrafo o un elenco compatto, ma deve essere incontrata prima che il lettore si impegni nel corpo. L’invocazione del TOC appartiene immediatamente dopo la panoramica in modo che la fonte mantenga insieme orientamento e navigazione, anche se il controllo adesivo di questo sito diventa visibile solo dopo 300 pixel di scorrimento.

La coppia non può interrompere una definizione, separare un’affermazione dalla sua prova, o apparire per la prima volta a metà del documento. Non posizionarla tra un’intestazione e il suo paragrafo di apertura: la relazione tra intestazione e spiegazione deve rimanere diretta. Non posizionare un altro componente simile a una panoramica immediatamente accanto. Quando sono richiesti un blocco di risposta diretta o punti chiave, assegna compiti distinti e usa quest’ordine: risposta diretta, breve panoramica della portata, invocazione del TOC, prima sezione del corpo. Ometti uno dei riepiloghi se la formulazione si sovrappone ancora.

Usa lo shortcode una volta per pagina. I suoi ID renderizzati (tocDropdown, tocSelect, selectTrigger e controlli correlati) sono fissi, quindi una seconda istanza crea ID di documento duplicati e script imprevedibili.

Anatomia

L’elemento ha sei regioni significative. Le prime cinque sono contenuto o comportamento; l’indicatore di progresso è di stato. La legenda è mantenuta nella pagina in modo che rimanga leggibile quando lo screenshot viene ridimensionato o sostituito.

1. Corpo della panoramica: 40–90 parole che dichiarano portata, risultato previsto e qualsiasi confine importante.
2. Titolo del wrapper adesivo: il titolo della pagina per impostazione predefinita, o l’attributo title quando un’etichetta più breve è più chiara.
3. Etichetta della sezione corrente: inizia come “Seleziona sezione…” e cambia man mano che l’IntersectionObserver del browser, un’API che rileva elementi che entrano in una regione del viewport definita, segna le sezioni come attive.
4. Trigger del menu a tendina: apre l’elenco generato delle destinazioni delle sezioni al clic nell’implementazione corrente.
5. Opzioni delle intestazioni: collegamenti derivati dall’indice dei contenuti della pagina di Hugo, attualmente H2 e H3 a causa di markup.toml.
6. Barra di avanzamento: mostra la proporzione del documento totale scorrevole attraversato; non identifica il completamento della sezione.

Esempi di design

La galleria copre gli stati di comportamento piuttosto che i temi decorativi. Il contenuto sottostante rimane lo stesso in modo che i revisori possano confrontare tempistiche, gerarchia, ritaglio e interazione.

Non vengono create varianti visive alternative tramite Markdown. title cambia l’etichetta e class aggiunge classi wrapper, ma nessuno dei due crea un elemento semanticamente diverso. Nuove varianti di colore, scheda, barra laterale o elenco in linea richiedono una decisione a livello di componente piuttosto che una classe arbitraria aggiunta nel contenuto.

Parametri

La panoramica e il TOC condividono un unico contratto editoriale, ma solo il TOC adesivo viene renderizzato dallo shortcode corrente. I valori di configurazione sono inclusi perché cambiano l’output anche se gli autori non possono impostarli per invocazione.

La dipendenza è facile da trascurare: una pagina senza intestazioni H2 renderizza silenziosamente nessun TOC adesivo perché Hugo non produce una struttura utilizzabile e il parziale emette markup solo quando ha intestazioni. Con la configurazione attuale, le H2 e i loro discendenti H3 sono idonei; le H4 e le intestazioni più profonde sono escluse. Il parziale normalmente analizza il .TableOfContents di Hugo. Il suo fallback HTML scansiona solo gli elementi H2 renderizzati, quindi gli autori non devono fare affidamento sul comportamento di fallback per preservare la navigazione H3.

Sintassi ed esempi di codice

La notazione portatile mantiene la panoramica come corpo dell’elemento e le impostazioni di navigazione come attributi. I collegamenti alle intestazioni rimangono generati dal documento circostante piuttosto che duplicati dall’autore.

:::quick-overview-and-toc{title="On this page" class=""}
Questa guida spiega quando usare l'elemento, come si comporta il controllo adesivo di Hugo
e come preservare destinazioni di sezione accessibili e stabili dopo la pubblicazione.
:::

La mappatura Hugo corrente scrive la panoramica come Markdown normale e invoca lo shortcode fornito una volta. Non c’è un corpo JSON.

Questa guida spiega quando usare l'elemento, come si comporta il controllo adesivo di Hugo
e come preservare destinazioni di sezione accessibili e stabili dopo la pubblicazione.

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

La mappatura del blocco WordPress memorizza lo stesso corpo e gli stessi attributi. Un sito che non ha registrato il blocco può usare la forma shortcode equivalente; non deve scrivere a mano i collegamenti alle intestazioni.

<!-- wp:amicited/quick-overview-and-toc {"title":"On this page","className":""} -->
<p>Questa guida spiega quando usare l'elemento, come si comporta il controllo adesivo
e come preservare destinazioni di sezione accessibili e stabili dopo la pubblicazione.</p>
<!-- /wp:amicited/quick-overview-and-toc -->

[amicited_quick_overview_toc title="On this page" class=""]
Questa guida spiega la portata, il comportamento e la politica delle ancore dell'elemento.
[/amicited_quick_overview_toc]

In tutti e tre i sistemi, la fonte di verità è la reale gerarchia delle intestazioni del documento. Un elenco mantenuto manualmente si discosterà man mano che le intestazioni cambiano e può puntare a ID che non sono più presenti.

Esempi

Buon esempio

Panoramica rapida. Questa guida mostra ai team di contenuti come pianificare, scrivere, revisionare e mantenere una pagina di confronto. Copre gli standard delle prove, i criteri di confronto, le affermazioni sui prodotti, le tabelle accessibili e i controlli post-pubblicazione. Non copre la collocazione a pagamento o i termini delle commissioni di affiliazione.

In questa pagina: Definisci la decisione · Seleziona i criteri di confronto · Raccogli le prove · Scrivi la bozza della pagina · Revisiona le affermazioni · Misura e mantieni

Funziona perché la panoramica nomina il pubblico, il risultato, la copertura e il confine in 48 parole. Le sei destinazioni sono compiti distinti che un lettore potrebbe rivisitare indipendentemente. Le loro etichette usano frasi verbali parallele, quindi sia le persone che le macchine possono dedurre un processo. Nessuna delle voci ripete il titolo della pagina o espone una sottosezione banale.

Cattivo esempio

Panoramica: Benvenuti nella nostra guida completa. Nel mondo di oggi in continuo cambiamento, c’è molto da sapere, quindi continua a leggere per imparare tutto.

Contenuti: Introduzione · Ulteriori informazioni · Cose importanti · Altre cose · Conclusione

Fallisce per due motivi. La panoramica spreca 22 parole senza definire portata, lettore, risultato o esclusione. Le voci etichettano contenitori retorici piuttosto che argomenti, quindi non aiutano un lettore a prevedere dove si trova una risposta. Aggiungere più intestazioni non lo risolverebbe; il documento ha prima bisogno di confini di sezione significativi.

Un secondo caso quasi sbagliato è una risposta di 600 parole con “Panoramica”, “Contesto”, “Dettagli”, “Suggerimenti” e “Conclusione” nel suo TOC. Anche se ogni ancoraggio funziona, l’elenco aggiunge più interfaccia che valore di navigazione. Mantieni l’apertura diretta e rimuovi il TOC.

Marcatura schema e accessibilità

Qui, marcatura schema significa codice standardizzato leggibile dalla macchina che identifica entità e proprietà. Questo elemento non ha un tipo o una proprietà dedicati nel vocabolario Schema.org, e lo shortcode Hugo non emette JSON-LD, la notazione basata su script comunemente usata per pubblicare quel vocabolario. Non marcare il TOC come ItemList solo perché è un elenco; ciò suggerirebbe un elenco di elementi dell’argomento piuttosto che navigazione. La panoramica può informare la description di una pagina solo quando la formulazione è autonomamente adatta, ma non viene copiata automaticamente nei dati strutturati.

Il comportamento HTML e ARIA è più importante qui. ARIA, lo standard Accessible Rich Internet Applications, fornisce ruoli, nomi e stati quando l’HTML nativo non lo fa. Un landmark è una regione di pagina nominata a cui gli utenti di tecnologie assistive possono saltare. Il focus è il target di interazione corrente della tastiera.

Questi sono fatti di implementazione, non permessi per ignorare l’accessibilità. I revisori dei contenuti possono verificare la chiarezza delle intestazioni, gli ID univoci e l’ordine logico oggi. I proprietari dei componenti devono risolvere il comportamento di trigger, landmark, focus, URL e movimento ridotto prima di descrivere la variante adesiva come accessibile da tastiera.

Regole di scrittura

Scrivi la panoramica dopo che la struttura della pagina è stabile. Questo impedisce che una promessa precoce si allontani dalla copertura finale. Mantienila tra 40 e 90 parole. Preferisci due o tre frasi; usa da tre a cinque punti elenco solo quando la pagina contiene diversi risultati veramente paralleli. Dichiara cosa la pagina aiuta il lettore a capire, decidere o fare. Nomina un’esclusione quando il titolo potrebbe ragionevolmente promettere più di quanto la pagina offra.

Usa H2 per le domande principali, le fasi o le aree decisionali della pagina. Includi H3 nella navigazione solo quando è una destinazione indipendente utile sotto una H2 sostanziale. Su questo sito, la configurazione include automaticamente ogni H2 e H3, quindi la policy pratica è più rigorosa: non creare un’intestazione a meno che non meriti di apparire nella navigazione. Punta a 5–18 voci totali. Se l’elenco generato supera le 18, combina sezioni sovrapposte, rimuovi le intestazioni H3 non necessarie o suddividi la pagina. Non saltare mai direttamente da H2 a H4 per nascondere un’intestazione dal TOC; i livelli di intestazione esprimono gerarchia, non preferenze di stile o navigazione.

Usa testo di intestazione conciso e descrittivo. Un lettore dovrebbe capire ogni destinazione senza leggere il paragrafo genitore. Preferisci forme parallele all’interno di una sequenza: “Scegli i criteri”, “Raccogli le prove” e “Revisiona le affermazioni” sono più facili da scansionare di un misto di sostantivi, domande ed etichette vaghe. Non inserire citazioni, affermazioni promozionali, emoji, badge di stato o frasi complete in un’intestazione solo per influenzare il TOC.

La panoramica non deve mai contenere un secondo mini-elenco dei contenuti, affermazioni di performance non supportate o istruzioni che non appaiono da nessuna parte nel corpo. Il TOC non deve mai contenere ancore digitate manualmente, destinazioni al di fuori della pagina corrente o collegamenti a sezioni vuote.

Politica di stabilità delle ancore

Un ID di intestazione è la parte del frammento di un URL, come #politica-di-stabilita-delle-ancore. I frammenti URL pubblicati sono interfacce pubbliche. Segnalibri, link di campagne, documentazione di supporto, risultati di ricerca e risposte generate dall’IA possono puntare direttamente a essi. Modificare il testo dell’intestazione può cambiare l’ID generato da Hugo e rompere ogni ancoraggio in entrata anche quando l’URL della pagina rimane lo stesso.

Dopo la pubblicazione, congela gli ID di tutte le intestazioni H2 e H3. Preferisci modificare il paragrafo sotto un’intestazione piuttosto che rinominare l’intestazione. Quando una rinomina è necessaria, preserva il vecchio ID utilizzando un meccanismo di ancoraggio esplicito supportato dal sistema di pubblicazione, poi verifica sia il vecchio frammento in entrata sia la nuova selezione del TOC. Non riutilizzare mai un vecchio ID per un argomento diverso, non duplicare mai un ID sulla pagina e non tradurre mai un ID su un URL localizzato esistente senza un piano di migrazione. Registra le modifiche intenzionali delle ancore nella nota di rilascio o nel registro delle modifiche dei contenuti in modo che i proprietari dei collegamenti in entrata noti possano aggiornarli.

Tipi di post che lo utilizzano

Il frontmatter postTypes elenca i formati per i quali questo elemento fa parte del pattern di produzione. È comunque condizionale: un’istanza breve di un formato normalmente lungo può essere al di sotto della soglia del TOC.

Le pagine di prodotto, categoria e caso d’uso non sono incluse per impostazione predefinita perché i loro percorsi primari sono spesso gestiti dalla navigazione a livello di pagina e dagli inviti all’azione. Aggiungi questo elemento solo attraverso una decisione documentata del template, non perché la pagina è lunga per caso.

Checklist QA

• Conferma che la pagina soddisfi la soglia: almeno 1.800 parole, sette sezioni H2 o una documentata esigenza di navigazione non lineare.
• Conferma che la panoramica sia di 40–90 parole e dichiari portata, risultato previsto e qualsiasi esclusione necessaria.
• Conferma che la panoramica non ripeta la risposta diretta o i punti chiave.
• Conferma che lo shortcode appaia una volta, immediatamente dopo la panoramica e prima della prima H2.
• Conferma che ogni H2 sia una destinazione principale significativa e ogni H3 sia sufficientemente utile da apparire nella navigazione.
• Conferma che l’elenco generato contenga 5–18 voci, utilizzi un ordine logico e non contenga elementi H4 con la configurazione corrente.
• Conferma che config/_default/markup.toml utilizzi ancora startLevel = 2, endLevel = 3 e ordered = false, oppure aggiorna questa specifica con la modifica del componente.
• Conferma che una pagina senza H2 idonee non dichiari di contenere un TOC; lo shortcode renderizzerà silenziosamente nulla.
• Conferma che ogni frammento generato sia univoco e raggiunga l’intestazione prevista.
• Testa gli URL di ancoraggio pubblicati in entrata prima di modificare qualsiasi formulazione di H2 o H3; preserva i vecchi ID quando le intestazioni devono cambiare.
• Sul desktop, verifica che il wrapper adesivo sia nascosto a 300 pixel o meno e appaia dopo che la posizione di scorrimento supera i 300 pixel.
• Verifica che il wrapper fisso sia posizionato sotto l’intestazione reale, la barra di avanzamento avanzi e l’etichetta attiva segua i cambiamenti di sezione.
• Verifica che i viewport stretti non mostrino il controllo corrente, e registra questo come comportamento corrente previsto piuttosto che come screenshot rotto.
• Registra le attuali limitazioni di accessibilità: nessun landmark di navigazione, nessun trigger visibile focalizzabile da tastiera, nessun trasferimento di focus, nessun aggiornamento del frammento e nessun ramo di movimento ridotto.
• Conferma che nessun percorso di screenshot venga renderizzato fino a quando l’asset corrispondente non esiste su disco.

FAQ

Le domande seguenti coprono le decisioni editoriali che più spesso portano questo elemento a essere aggiunto troppo presto, reso troppo profondo o danneggiato dopo la pubblicazione.