Innehållsförteckning: Format och regler

I elementbiblioteket berättar en snabböversikt och innehållsförteckning för läsarna vad en sida täcker, vad den hjälper dem att avgöra och hur de hoppar till det avsnitt de behöver.

Snabböversikt. Använd detta par av inledande element på långa eller strukturellt komplexa sidor. Skriv en översikt på 40–90 ord som anger omfattning och förväntat resultat, tillhandahåll sedan en innehållslista som bygger på stabila H2-rubriker och endast användbara H3-rubriker. På den här webbplatsen förblir live-innehållskontrollen nedan dold tills läsaren har scrollat mer än 300 pixlar; den visas då som en fast dropdown för stationära datorer under webbplatshuvudet.

Varför detta element är viktigt

Läsare börjar inte varje lång sida på samma ställe. En person behöver en definition, en annan vill ha implementationssteg och en tredje kontrollerar en enda begränsning innan arbetet godkänns. En kort översikt svarar på “Är jag på rätt plats?” innan läsaren investerar uppmärksamhet. Innehållslistan svarar på “Var finns den del jag behöver?” utan att tvinga fram en linjär läsning.

De två delarna specificeras tillsammans eftersom de löser närliggande men olika orienteringsproblem. Översikten förklarar sidans löfte, gränser och användbara resultat i meningar. Innehållslistan exponerar vägen genom det löftet som destinationer. En innehållslista utan översikt kan visa att en sida har avsnitt som kallas “Konfiguration” och “Tillgänglighet” men kan inte förklara om sidan är en konceptuell introduktion eller en produktionsspecifikation. En översikt utan navigering kan etablera omfattning men ändå få en läsare att leta igenom 3 000 ord.

Detta element förbättrar också maskinell extraherbarhet, vilket innebär förmågan hos programvara att isolera ett avsnitt och behålla dess syfte utanför hela sidan. Översikten är en andra kortfattad, självständig sammanfattning efter titeln och beskrivningen. Hugos källinnehållsförteckning är en länkad, maskinläsbar disposition av sidans täckning och hierarki; den nuvarande fasta renderaren omvandlar dessa länkar till alternativ som behåller sina URL-fragmentvärden, #-delen av en URL. Söksystem, hämtningsverktyg, webbläsartillägg och AI-agenter kan använda dokumentdispositionen för att identifiera sannolika svarsregioner innan de bearbetar varje stycke. Detta garanterar inte en sökfunktion eller AI-citering; det minskar oklarhet om var ämnen börjar och hur de förhåller sig.

Parningen får inte skapa upprepning. En översikt anger omfattning och resultat. Ett blocksvar svarar på den primära frågan. Viktiga slutsatser anger slutsatser värda att komma ihåg. När alla tre säger samma sak i olika rutor blir inledningen ett hinder snarare än ett hjälpmedel.

När du ska använda det

Innehållslistan förtjänar sin plats när hoppning är ett sannolikt läsarbeteende. Ordantal är en användbar indikator, men struktur är den avgörande faktorn.

Använd enbart översikten när titeln kan tolkas brett, när sidan medvetet utesluter närliggande ämnen, eller när läsaren behöver veta det förväntade resultatet innan de fortsätter. En 900-ords policiesida kan behöva en översikt på två meningar även om den inte behöver navigering.

Använd enbart innehållslistan när titeln och inledningen redan gör omfattningen otvetydig. Detta nära-undantag är vanligt på referenssidor: inledningen kan innehålla en direkt definition som utför orienteringsarbetet, medan en lång uppsättning oberoende fält fortfarande behöver navigering.

Använd inte någon av delarna som dekoration. En innehållsförteckning med sex punkter på en 700-ords artikel lägger till ett extra beslut innan svaret. En översikt som säger “Den här guiden utforskar allt du behöver veta” definierar inte omfattning, resultat eller undantag. Använd inte paret för att dölja en svag rubrikstruktur: om rubriker överlappar, använder inkonsekvent grammatik, eller delar upp en idé i många små avsnitt, åtgärda dokumentet innan du exponerar dess disposition.

Var du ska placera det

Position är en del av elementets betydelse. Översikten måste visas efter hjälten eller det inledande blocksvaret och före den första H2. Den kan vara ett kort stycke eller en kompakt lista, men den måste påträffas innan läsaren förbinder sig till brödtexten. Innehållsförteckningsanropet hör hemma omedelbart efter översikten så att den skrivna källan håller orientering och navigering tillsammans, även om webbplatsens fasta kontroll blir synlig först efter 300 pixlars scrollning.

Paret får inte avbryta en definition, separera ett påstående från dess bevis, eller dyka upp för första gången mitt i dokumentet. Placera det inte mellan en rubrik och rubrikens inledande stycke: förhållandet mellan rubrik och förklaring bör förbli direkt. Placera ingen annan översiktsliknande komponent omedelbart intill den. När ett blocksvar eller viktiga slutsatser krävs, tilldela olika uppgifter och använd denna ordning: blocksvar, kort omfattningsöversikt, innehållsförteckningsanrop, första brödtextavsnitt. Utelämna en av sammanfattningarna om ordalydelsen fortfarande överlappar.

Använd kortkoden en gång per sida. Dess renderade ID:n (tocDropdown, tocSelect, selectTrigger och relaterade kontroller) är fasta, så en andra instans skapar dubbletter av dokument-ID:n och oförutsägbara skript.

Anatomi

Elementet har sex meningsfulla regioner. De första fem är innehåll eller beteende; förloppsindikatorn är status. Förklaringen finns kvar på sidan så att den förblir läsbar när skärmbilden ändrar storlek eller byts ut.

1. Översiktskropp: 40–90 ord som anger omfattning, avsett resultat och eventuell viktig gräns.
2. Fast omslagstitel: sidtiteln som standard, eller det skrivna title-attributet när en kortare etikett är tydligare.
3. Aktuell-avsnittsetikett: börjar som “Välj avsnitt…” och ändras när webbläsarens IntersectionObserver, ett API som upptäcker element som kommer in i en definierad visningsportsregion, markerar avsnitt som aktiva.
4. Dropdown-utlösare: öppnar den genererade listan med avsnittdestinationer vid klick i den aktuella implementationen.
5. Rubrikalternativ: länkar som härleds från Hugos sidinnehållsförteckning, för närvarande H2 och H3 på grund av markup.toml.
6. Förloppsindikator: visar andelen av det totala scrollbara dokumentet som genomkorsats; den identifierar inte avsnittsslutförande.

Designexempel

Gallriet täcker beteendetillstånd snarare än dekorativa teman. Det underliggande innehållet förblir detsamma så att granskare kan jämföra tidpunkt, hierarki, beskärning och interaktion.

Inga alternativa visuella varianter skapas via Markdown. title ändrar etiketten och class lägger till omslagsklasser, men ingen av dem skapar ett semantiskt annorlunda element. Nya färg-, kort-, sidofälts- eller inline-listbehandlingar kräver ett komponentbeslut snarare än en godtycklig klass tillagd i innehåll.

Parametrar

Översikten och innehållsförteckningen delar ett redaktionellt kontrakt, men endast den fasta innehållsförteckningen renderas av den aktuella kortkoden. Konfigurationsvärden inkluderas eftersom de ändrar utdata även om författare inte kan ställa in dem per anrop.

Beroendet är lätt att missa: en sida utan H2-rubriker renderar tyst ingen fast innehållsförteckning eftersom Hugo inte producerar någon användbar disposition och delen endast genererar markup när den har rubriker. Med den nuvarande konfigurationen är H2 och deras H3-avkomlingar kvalificerade; H4 och djupare rubriker är exkluderade. Delen tolkar normalt Hugo .TableOfContents. Dess HTML-reserv skannar endast renderade H2-element, så författare får inte förlita sig på reservbeteende för att bevara H3-navigering.

Syntax och kodexempel

Den portabla notationen håller översikten som elementkropp och navigeringsinställningarna som attribut. Rubriklänkar förblir genererade från det omgivande dokumentet snarare än duplicerade av författaren.

:::quick-overview-and-toc{title="På denna sida" class=""}
Denna guide förklarar när du ska använda elementet, hur den fasta Hugo-kontrollen beter sig
och hur du bevarar tillgängliga, stabila avsnittdestinationer efter publicering.
:::

Den nuvarande Hugo-mappningen skriver översikten som vanlig Markdown och anropar den medföljande kortkoden en gång. Det finns ingen JSON-kropp.

Denna guide förklarar när du ska använda elementet, hur den fasta Hugo-kontrollen beter sig,
och hur du bevarar tillgängliga, stabila avsnittdestinationer efter publicering.

{{< table-of-contents title="På denna sida" class="" >}}

WordPress-blockmappningen lagrar samma kropp och attribut. En webbplats som inte har registrerat blocket kan använda motsvarande kortkodsform; den får inte skriva rubriklänkarna för hand.

<!-- wp:amicited/quick-overview-and-toc {"title":"På denna sida","className":""} -->
<p>Denna guide förklarar när du ska använda elementet, hur den fasta kontrollen beter sig,
och hur du bevarar tillgängliga, stabila avsnittdestinationer efter publicering.</p>
<!-- /wp:amicited/quick-overview-and-toc -->

[amicited_quick_overview_toc title="På denna sida" class=""]
Denna guide förklarar elementets omfattning, beteende och ankarpolicy.
[/amicited_quick_overview_toc]

I alla tre systemen är sanningens källa dokumentets faktiska rubrikhierarki. En manuellt underhållen lista kommer att avvika när rubriker ändras och kan peka på ID:n som inte längre finns.

Exempel

Bra exempel

Snabböversikt. Denna guide visar innehållsteam hur de planerar, skriver, granskar och underhåller en jämförelsesida. Den täcker bevisstandarder, jämförelsekriterier, produktpåståenden, tillgängliga tabeller och kontroller efter publicering. Den täcker inte betald placering eller affiliate-provisionsvillkor.

På denna sida: Definiera beslutet · Välj jämförelsekriterier · Samla bevis · Utkast till sidan · Granska påståenden · Mät och underhåll

Detta fungerar eftersom översikten namnger målgrupp, resultat, täckning och gräns på 48 ord. De sex destinationerna är distinkta uppgifter en läsare kan återkomma till oberoende. Deras etiketter använder parallella verbformer, så både människor och maskiner kan härleda en process. Ingen av posterna upprepar sidtiteln eller exponerar en trivial underavdelning.

Dåligt exempel

Översikt: Välkommen till vår kompletta guide. I dagens föränderliga värld finns det mycket att veta, så läs vidare för att lära dig allt.

Innehåll: Introduktion · Mer information · Viktiga saker · Andra saker · Slutsats

Detta misslyckas av två anledningar. Översikten använder 22 ord utan att definiera omfattning, läsare, resultat eller undantag. Posterna etiketterar retoriska behållare snarare än ämnen, så de hjälper inte en läsare att förutsäga var ett svar finns. Att lägga till fler rubriker skulle inte åtgärda det; dokumentet behöver meningsfulla avsnittsgränser först.

Ett andra nära-undantag är en 600-ords svarssida med “Översikt”, “Bakgrund”, “Detaljer”, “Tips” och “Slutsats” i sin innehållsförteckning. Även om varje ankare fungerar, lägger listan till mer gränssnitt än navigeringsvärde. Behåll den direkta inledningen och ta bort innehållsförteckningen.

Schema-markup och tillgänglighet

Här betyder schema-markup standardiserad maskinläsbar kod som identifierar entiteter och egenskaper. Detta element har ingen dedikerad typ eller egenskap i Schema.org-vokabulären, och Hugo-kortkoden genererar ingen JSON-LD, den skriptbaserade notationen som vanligtvis används för att publicera den vokabulären. Märk inte innehållsförteckningen som ItemList enbart för att den är en lista; det skulle antyda en lista med ämnesobjekt snarare än navigering. Översikten kan informera en sidas description endast när ordalydelsen är oberoende lämplig, men den kopieras inte automatiskt till strukturerad data.

HTML- och ARIA-beteende är viktigare här. ARIA, standarden för tillgängliga rika internetapplikationer, tillhandahåller roller, namn och tillstånd när inbyggd HTML inte gör det. Ett landmärke är en namngiven sidregion som användare av hjälpmedelsteknik kan hoppa till. Fokus är det aktuella tangentbordsinteraktionsmålet.

Dessa är implementationsfakta, inte tillstånd att ignorera tillgänglighet. Innehållsgranskare kan verifiera rubriktydlighet, unika ID:n och logisk ordning idag. Komponentägare måste lösa utlösar-, landmärkes-, fokus-, URL- och reducerad-rörelse-beteende innan de beskriver den fasta varianten som tangentbordstillgänglig.

Skrivregler

Skriv översikten efter att sidstrukturen är stabil. Detta förhindrar att ett tidigt löfte driver bort från den färdiga täckningen. Håll den mellan 40 och 90 ord. Föredra två eller tre meningar; använd tre till fem punkter endast när sidan innehåller flera genuint parallella resultat. Ange vad sidan hjälper läsaren att förstå, avgöra eller göra. Namnge ett undantag när titeln rimligen kan lova mer än sidan levererar.

Använd H2 för sidans huvudsakliga frågor, stadier eller beslutsområden. Inkludera H3 i navigering endast när det är en användbar oberoende destination under en omfattande H2. På denna webbplats inkluderar konfigurationen automatiskt varje H2 och H3, så den praktiska policyn är strängare: skapa inte en rubrik om den inte förtjänar att visas i navigering. Sikta på 5–18 totala poster. Om den genererade listan överstiger 18, kombinera överlappande avsnitt, ta bort onödiga H3-rubriker eller dela upp sidan. Hoppa aldrig direkt från H2 till H4 för att dölja en rubrik från innehållsförteckningen; rubriknivåer uttrycker hierarki, inte styling eller navigeringspreferens.

Använd kortfattad, beskrivande rubriktext. En läsare bör förstå varje destination utan att läsa dess överordnade stycke. Föredra parallella former inom en sekvens: “Välj kriterier”, “Samla bevis” och “Granska påståenden” är lättare att skanna än en blandning av substantiv, frågor och vaga etiketter. Placera inte citat, reklampåståenden, emoji, statusmärken eller hela meningar i en rubrik enbart för att påverka innehållsförteckningen.

Översikten får aldrig innehålla en andra miniatyrinnehållslista, ogrundade prestandapåståenden eller instruktioner som inte förekommer i brödtexten. Innehållsförteckningen får aldrig innehålla manuellt inskrivna ankare, destinationer utanför den aktuella sidan eller länkar till tomma avsnitt.

Policy för ankarstabilitet

En rubriks ID är fragmentdelen av en URL, såsom #anchor-stability-policy. Publicerade fragment-URL:er är offentliga gränssnitt. Bokmärken, kampanjlänkar, supportdokumentation, sökresultat och AI-genererade svar kan peka direkt på dem. Att ändra rubriktexten kan ändra Hugos genererade ID och bryta varje inkommande ankare även när sidans URL förblir densamma.

Efter publicering, frys ID:n för alla H2- och H3-rubriker. Föredra att redigera stycket under en rubrik framför att byta namn på rubriken. När en namnändring är nödvändig, bevara det gamla ID:t med en explicit ankarmekanism som stöds av publiceringssystemet, verifiera sedan både det gamla inkommande fragmentet och den nya innehållsförteckningens val. Återanvänd aldrig ett gammalt ID för ett annat ämne, duplicera aldrig ett ID på sidan, och översätt aldrig ett ID på en befintlig lokaliserad URL utan en migreringsplan. Registrera avsiktliga ankareändringar i versionsnoteringen eller innehållsändringsloggen så att ägare av kända inkommande länkar kan uppdatera dem.

Posttyper som använder det

Frontmatter-fältet postTypes listar formaten för vilka detta element ingår i produktionsmönstret. Det är fortfarande villkorligt: ett kort exemplar av ett normalt långt format kan falla under innehållsförteckningströskeln.

Produkt-, kategori- och användningsfallsidor ingår inte som standard eftersom deras primära resor ofta hanteras av sidnavigering och uppmaningar till handling. Lägg till detta element endast genom ett dokumenterat mallbeslut, inte för att sidan råkar vara lång.

QA-checklista

• Bekräfta att sidan uppfyller tröskelvärdet: minst 1 800 ord, sju H2-avsnitt eller ett dokumenterat icke-linjärt navigeringsbehov.
• Bekräfta att översikten är 40–90 ord och anger omfattning, avsett resultat och eventuellt nödvändigt undantag.
• Bekräfta att översikten inte upprepar blocksvaret eller viktiga slutsatser.
• Bekräfta att kortkoden visas en gång, omedelbart efter översikten och före den första H2.
• Bekräfta att varje H2 är en meningsfull huvuddestination och varje H3 är tillräckligt användbar för att visas i navigering.
• Bekräfta att den genererade listan innehåller 5–18 poster, använder en logisk ordning och inte innehåller H4-objekt under den nuvarande konfigurationen.
• Bekräfta att config/_default/markup.toml fortfarande använder startLevel = 2, endLevel = 3 och ordered = false, eller uppdatera denna specifikation med komponentändringen.
• Bekräfta att en sida utan kvalificerade H2 inte påstår sig innehålla en innehållsförteckning; kortkoden kommer att renderar ingenting tyst.
• Bekräfta att varje genererat fragment är unikt och når den avsedda rubriken.
• Testa publicerade inkommande ankar-URL:er innan du ändrar någon H2- eller H3-ordalydelse; bevara gamla ID:n när rubriker måste ändras.
• På stationär dator, verifiera att det fasta omslaget är dolt vid 300 pixlar eller mindre och visas efter att scrollpositionen överstiger 300 pixlar.
• Verifiera att det fasta omslaget sitter under den faktiska rubriken, förloppsindikatorn avancerar och den aktiva etiketten följer avsnittsförändringar.
• Verifiera att smala visningsportar inte visar den aktuella kontrollen, och dokumentera detta som förväntat nuvarande beteende snarare än en trasig skärmbild.
• Dokumentera de nuvarande tillgänglighetsbegränsningarna: inget navigeringslandmärke, ingen tangentbordsfokuserbar synlig utlösare, ingen fokusöverföring, ingen fragmentuppdatering och ingen reducerad-rörelse-gren.
• Bekräfta att ingen skärmbildsväg renderas förrän motsvarande tillgång finns på disk.

FAQ

Frågorna nedan täcker de redaktionella beslut som oftast gör att detta element läggs till för tidigt, görs för djupt eller går sönder efter publicering.