Regler för innehållselement: När du ska använda varje block

Varje sida i SEO-spelboken beror på en distinktion: en innehållsdel har ett syfte, medan dess rubriknivå och visuella utseende bara är presentation. Dessa elementskrivregler omvandlar den distinktionen till ett produktionskontrakt. Följ dem innan du tillämpar någon komponent, konverterar en artikel mellan publiceringssystem eller ändrar ett element som redan förekommer på publicerade sidor.

Snabböversikt

• Kontrollera elementbiblioteket efter syfte före namn. Om ett elements syfte matchar den uppgift ett avsnitt utför, är det elementet obligatoriskt.
• Använd vanlig Markdown först efter att du bekräftat att inget typsatt element representerar avsnittets syfte. Fritext är en reserv, inte en standard.
• Skriv hela artikeln som vanlig text först. Applicera element i en separat strukturell genomgång uppifrån och ner så att komposition och märkspråk inte konkurrerar om uppmärksamheten.
• Behandla Markdown-direktivet som kanoniskt skapat innehåll. Hugo- och WordPress-renderare kartlägger samma fält och brödtext till plattformsspecifik utdata.
• Behåll befintliga publicerade sidor på den innebörd de granskades mot. En brytande definitionsändring skapar en ny version och en explicit migrering; den omtolkar aldrig gammalt innehåll i tysthet.

Den styrande prioritetsregeln

Biblioteket måste kontrolleras efter vad ett avsnitt gör, inte efter vad skribanten råkar kalla det. Namn varierar: en skribent kan rubriksätta ett avsnitt “Vad är churn?”, en annan “Churn förklarat” och en tredje “En fungerande definition”. Deras syfte är identiskt, så alla tre kartlägger till samma definitionselement.

Denna prioritet finns eftersom fritext och ett typsatt element kan se identiska ut på skärmen medan de beter sig helt annorlunda i efterföljande led. En stiliserad rubrik följd av ett stycke kan likna en definitionsruta i webbläsaren, men den bär ingen komponentidentitet. Den kan inte på ett tillförlitligt sätt producera definitionens strukturerade utdata, exponera dess fält för en annan renderare, behålla sin semantik under migrering eller hittas av en kvalitetskontroll som frågar om sidan innehåller en definition. Det typsatta elementet kartlägger till en komponent och en känd dataform; visuellt liknande fritext kartlägger till ingenting.

Regeln är därför strikt:

Innan du skriver eller godkänner någon rubrik eller innehållsblock, identifiera dess syfte. Om det syftet matchar en elementdefinition, använd elementet. Visuell likhet, en befintlig H2 eller förmågan att uttrycka samma ord i ett stycke gör inte fritext likvärdig.

Prioriteten är semantisk snarare än visuell. En sida kan fortfarande innehålla vanliga rubriker i eller runt ett element när dess definition tillåter det, men rubriken ersätter aldrig elementtypen.

Fritext kontra ett typsatt element

Använd denna beslutsväg tills det delade diagrammet finns tillgängligt:

1. Ange avsnittets uppgift med ett verb. Exempel inkluderar definiera, varna, sammanfatta, jämföra, bevisa, instruera eller uppmana till handling. Detta förhindrar att rubriktexten döljer det underliggande syftet.
2. Sök i biblioteket efter det syftet och dess synonymer. En skribent som bara letar efter den bokstavliga rubriken “Vad är X?” kan missa ett definitionselement vars sida heter “Definitionsruta”.
3. Använd det matchande elementet när ett finns. Jämför inte utseenden eller fråga om Markdown kan imitera designen; det registrerade beteendet är den avgörande faktorn.
4. Använd fritext när inget syfte matchar. Detta är korrekt för sammanbindande förklaringar, argument, analys, narrativ kontext och övergångar som tillhör artikelns huvudflöde och inte kräver något distinkt komponentbeteende.
5. Dokumentera ett återkommande gap. Om samma omatchade syfte förekommer på flera sidor, föreslå ett bibliotekselement istället för att uppfinna ett engångsdirektiv eller en CSS-behandling i en artikel.

Vanlig Markdown är genuint korrekt när orden utgör artikelns löpande resonemang och inte behöver en oberoende etikett, datakontrakt, interaktion eller återanvändningsväg. Till exempel är två stycken som förklarar varför en rekommendation följer av föregående bevis normal prosa. En kompakt uppsättning slutsatser i början är inte normal prosa bara för att den kan skrivas som punkter; den har det erkända syftet som ett översikts- eller slutsatserelement.

Vanliga förväxlingar som orsakar felaktig märkning

Dessa fall listas explicit eftersom de lätt passerar en visuell granskning. Misstaget blir synligt först när en annan renderare, validerare, sökindex eller konsument av strukturerad utdata tar emot sidan.

Skillnaden mellan viktiga slutsatser och en snabböversikt är särskilt viktig. Använd slutsatser när punkterna är resultat läsaren bör komma ihåg, vilket innebär att de ofta bara kan skrivas efter att artikeln existerar. Använd en översikt när punkterna orienterar läsaren om omfattning eller sekvens innan läsning. Välj baserat på det redaktionella arbetet, även om det aktuella temat får båda komponenterna att se likadana ut.

Direktiv- och attributsyntax

Den kanoniska Markdown-formen använder ett namngivet blockdirektiv. Attribut följer direktivnamnet inom klamrar:

:::element-name{nyckel=värde nyckel2="värde med mellanslag" .class}
Brödtext
:::

Attribut finns för att bära små, stabila egenskaper som påverkar elementets innebörd eller presentation som stöds. Att hålla dem maskinläsbara förhindrar att skribenter gömmer konfiguration i prosa. Använd nyckel=värde för ett värde utan mellanslag och nyckel2="värde med mellanslag" när mellanslag förekommer. Ett ociterat attributvärde får inte innehålla mellanslag. En inledande punkt lägger till en klass som stöds, som i .compact; det är inte en plats att uppfinna sidspecifik styling.

Attributnycklar är gemener och använder den exakta stavning som definierats på elementsidan. Booleska och uppräknade värden följer också den sidans kontrakt. Skapa inte ett attribut för att en renderare råkar tolerera det: ett odeklarerat attribut har ingen plattformsoberoende garanti.

Avslutande :::-avgränsare tillhör det yttre elementet. Håll dem på egna rader så att en parser kan skilja brödtexten från nästa stycke. Kodexempel som demonstrerar direktiv måste hållas inom avgränsade kodblock, som de gör på denna sida, så att Hugo inte tolkar dem som innehåll.

Standard brödtextmappning

De flesta element behöver en kort titel och en längre brödtext. Att kräva att författare upprepar dessa som attribut skulle göra lång text svårredigerad och lätt att undkomma felaktigt, så brödtexten tillhandahåller standardmappningen:

:::exempel
## En konkret rubrik

Resten av brödtexten kan innehålla stycken, listor, länkar och annat innehåll som tillåts av elementdefinitionen.
:::

Om inte en elementsida explicit åsidosätter regeln, kartläggs den första rubriken i brödtexten till title, och allt efter den rubriken kartläggs till content. Rubrikmarkören uttrycker källhierarki för redaktörer; det mappade fältet låter varje plattform rendera den lämpliga semantiska rubriknivån i sammanhanget.

Endast den första brödtextrubriken får denna särbehandling. Senare rubriker förblir en del av content. Om brödtexten saknar rubrik är title frånvarande; det är endast giltigt när elementdefinitionen markerar sin titel som valfri. Om ett element definierar namngivna platser eller en annan mappning har dess egen sida företräde framför denna standard eftersom renderaren måste veta exakt var varje fragment hör hemma.

Nästlade objekt

Vissa element innehåller en repeterbar lista vars poster var och en behöver attribut och en brödtext, såsom steg med identifierare, kort med etiketter eller checklisteobjekt med ett initialt tillstånd. Att platta till dessa poster i en Markdown-lista skulle förlora deras individuella fält, så nästlade objekt använder ett explicit objekt-direktiv:

:::fördlder-element{variant=kompakt}
::objekt{nyckel=värde}
### Första objektets titel

Den första objektets förklaring.
::
::objekt{nyckel2="värde med mellanslag"}
### Andra objektets titel

Det andra objektets förklaring.
::
:::

Kontraktet är ::objekt{nyckel=värde} … ::: två kolon öppnar varje objekt, singularnamnet är objekt, och två kolon stänger det. Föräldern behåller sin treskolons avslutande avgränsare. Denna visuella skillnad är viktig eftersom den gör nästling entydig utan att förlita sig på indrag, som lätt skadas av kopiera-och-klistra.

Varje objekt tillämpar samma standard brödtextmappning om inte förälderelementets sida anger något annat: dess första rubrik blir det objektets title, och resten blir dess content. Placera attribut på objektet när de beskriver endast det objektet; placera dem på föräldern när de påverkar samlingen som helhet.

Länkar, bilder och inline-knappar

Portabel källa behöver förutsägbara sökvägar. En relativ URL bör vara relativ webbplatsroten, inte till den aktuella Markdown-filen, eftersom samma källa kan renderas på ett annat filsystems djup i Hugo eller importeras till WordPress.

• Interna sidlänkar använder ett inledande och avslutande snedstreck, som elementbiblioteket -länken gör. Använd inte ../, utelämna inte det inledande snedstrecket eller hårdkoda produktionsdomänen för en intern sida.
• Externa länkar använder en fullständig https://-URL. Schemat är en del av destinationen och får inte antas av en renderare.
• Bildkällfiler finns under cdn-assets/seo-playbook/, och deras publika sökvägar börjar med /cdn-assets/seo-playbook/. Lägg till den godkända gruppen och filnamnet först efter att tillgången existerar.
• Alternativtext beskriver informationen som förmedlas av en bild, inte dess filnamn eller dekorativa utseende. En dekorativ bild använder en tom alternativtext, men den relevanta elementsidan måste explicit tillåta dekoration.
• En inline-uppmaning till handling använder :button[Synlig etikett]{href="/mål/"}. Den text som står inom hakparenteser är den tillgängliga etiketten och href följer samma regler för interna eller externa sökvägar. Använd en knapp endast för en genuin nästa åtgärd, inte för att göra en vanlig referenslänk mer framträdande.

En bild är innehåll, inte en kringgående lösning för layout som inte stöds. Om bilden innehåller väsentliga etiketter, siffror eller instruktioner, upprepa den informationen i tillgänglig text eller använd ett strukturerat element som exponerar den. Skärmbildsfångster förblir HTML-kommentarer tills den namngivna tillgången existerar; de är inte publicerade bildreferenser och måste ha screenshotsPending = true i frontmatter.

Frontmatter och brödtextelement har olika uppgifter

Frontmatter beskriver dokumentet som ett dokument. Brödtextdirektiv beskriver meningsfulla block inom läsupplevelsen. Att hålla dessa lager separata låter listningssidor, scheman, routning och publiceringsverktyg läsa metadata utan att tolka synlig prosa.

Metadataelement lever därför i frontmatter: sidtitel, beskrivning, nyckelord, publicerings- och uppdateringsdatum, kanonisk information eller alias, ägarskap, taxonomi, spelboksanslutningar och alla schemaorienterade samlingar som sidkontraktet placerar där, såsom FAQ-poster på akademisidor. Dessa fält skrivs aldrig som :::-direktiv. Ett synligt block som upprepar viss metadata flyttar inte det auktoritativa fältet ur frontmatter; det får sitt eget brödtextelement endast när det har ett separat läsarriktat syfte.

Innehållselement lever i brödtexten: definitioner, varningar, tips, översikter, slutsatser, checklistor, jämförelser, bevisblock, exempel, steg och uppmaningar till handling. De är direktiv eftersom deras placering i berättelsen har betydelse. Att flytta en varning till frontmatter skulle koppla bort den från avsnittet den kvalificerar; att dölja metadata i ett brödtextdirektiv skulle göra att dokumentsystem inte kan hitta den på ett tillförlitligt sätt.

Metadata krävs som standard

Metadata driver sökvägar, förhandsvisningar, upptäckbarhet, anslutningar och strukturerad utdata innan någon läser brödtexten. Ett utelämnat fält kan därför bryta konsumenter som aldrig renderar artikeln. Av den anledningen är varje metadataelement obligatoriskt om inte dess elementsida explicit säger att det är valfritt.

Obligatoriskt innebär ifyllt med ett giltigt värde, inte bara närvarande som en tom sträng eller tom samling. Sluta dig inte till valfrihet från en annan sidas utelämnande, och lägg inte till platshållarvärden för att uppfylla validering. Om ett obligatoriskt värde ännu inte är känt är sidan inte redo att publiceras. Brödtextelement följer kravreglerna för den relevanta posttypen och elementsidorna snarare än denna metadatastandard.

Skriv först, applicera element sedan

Elementval är en klassificeringsuppgift, medan utkastskrivning är en resonemangsuppgift. Att försöka utföra båda mening för mening gör att skribenten optimerar i förtid för komponentgränser. Det vanliga resultatet är svagare övergångar, ytliga förklaringar anpassade till en ruta, repetitiva rubriker skapade för att uppfylla märkspråk och direktiv valda för att de är bekväma snarare än för att deras syfte matchar.

Produktion sker därför i två distinkta omgångar:

1. Skriv hela artikeln som vanlig text. Fullborda argumentet, exemplen, kvalifikationerna, övergångarna och slutsatsen. I detta skede kan rubriker beskriva utkastets logik, men de avgör inte den slutliga elementtypen.
2. Applicera element i en separat genomgång uppifrån och ner. För varje rubrik och block, ange dess syfte, kontrollera biblioteket, omslut matchande avsnitt, lägg till deklarerade attribut och bekräfta brödtextmappning och nästling.

Separationen förbättrar båda utdatan. Prosan utvecklas enligt läsarens frågor istället för det aktuella temats rutstorlekar, medan märkspråksgenomgången kan jämföra liknande block konsekvent över hela dokumentet. Det gör också utelämnanden synliga: en skribent kan se att artikeln innehåller en varning eller definition innan hen bestämmer hur den ska kodas.

Efter den strukturella genomgången, läs sidan en gång utan att titta på direktivnamnen. Element måste stödja en sammanhängande artikel, inte förvandla den till en stapel av frånkopplade widgetar. Inspektera sedan källan en gång utan att bedöma prosan, verifiera avgränsare, attribut, nästlade objekt, sökvägar och obligatorisk metadata.

Trekontraktsavtalet

Ett element definieras en gång av dess syfte, kanoniska fält, tillåtna värden, brödtextmappning, tillgänglighetsbeteende, beteende för strukturerad utdata och version. Den definitionen är den slutgiltiga sanningen. De tre plattformsnotationerna är adaptrar till den, inte tre oberoende komponentdesigner.

De representativa formerna förklarar mappningen; den individuella elementsidan publicerar sitt exakta namn och fält som stöds. Författare arbetar i notationen som krävs av deras publiceringsarbetsflöde, men de byter inte namn på fält, lägger till plattformsspecifika innebörder eller imiterar manuellt en annan renderares HTML.

Elementägaren underhåller den kanoniska definitionen och avgör om en föreslagen ändring är kompatibel eller versionshanterad. Hugo- och WordPress-ansvariga äger sina adaptrar och testar dem mot delade testdata: samma titel, innehåll, attribut, objekt, länkar och tillgänglighetsförväntningar måste överleva alla tre vägarna. Redaktionella ägare verifierar syfte och exempel. Ingen plattformsansvarig får omdefiniera den redaktionella innebörden lokalt; om en plattform inte kan uttrycka kontraktet är det ett adapterfel eller ett föreslaget kontraktsändring.

Denna modell tillåter att presentation skiljer sig åt där plattformar kräver det samtidigt som semantiken hålls stabil. Hugo kan rendera server-side HTML och WordPress kan lagra en blockkommentar, men en varning förblir en varning, ett checklisteobjekt förblir ett objekt, och samma obligatoriska fält förblir tillgängliga i efterföljande led.

Versionshantering av publicerade element

Publicerat innehåll granskades mot den elementinnebörd som fanns vid publiceringstillfället. Att i tysthet ändra den innebörden kan ändra varningar, strukturerad data, tillgänglighet eller importer utan att en redaktör rör sidan. Versionshantering skyddar den redaktionella godkännandet.

Använd följande ändringspolicy:

• Kompatibel renderarändring: En visuell förfining, prestandaförbättring eller felkorrigering som bevarar syfte, fält, accepterade värden, brödtextmappning och utdatainnebörd kan lanseras inom den aktuella versionen. Befintliga sidor får den genom renderaren.
• Kompatibel additiv ändring: Ett nytt valfritt attribut får ansluta till den aktuella versionen endast när dess frånvaro bevarar befintlig utdata och varje adapter säkert kan ignorera eller stödja det. Definitionen och plattformstesterna ändras tillsammans.
• Brytande ändring: Ett omdöpt eller borttaget fält, ett nytt obligatoriskt fält, ändrad brödtextmappning, ändrat syfte, ändrad standard med semantisk effekt eller inkompatibel nästlad objektstruktur skapar en ny huvudversion av elementet.
• Fasas ut: Den gamla versionen förblir renderingsbar för publicerade sidor. Dess elementsida identifierar ersättningen och migreringsvägen; nya sidor använder den aktuella versionen.
• Migrering: En innehållsmigrering är explicit, avgränsad, förhandsgranskad över Markdown, Hugo och WordPress, och redaktionellt validerad före publicering. Dokumentera vilka sidor som ändrades och varför. Låt inte en renderare gissa hur gammal källa ska omtolkas.

När ingen version är skriven i källan använder elementet baslinjeversionen som definierades när detta kontrakt antogs. Den implicita baslinjen måste förbli stabil. Nya huvudversioner identifierar sig själva med hjälp av versionsmekanismen som deklareras på elementsidan; de återanvänder inte den oversionerade syntaxen.

Återställning är också viktig. Behåll föregående renderare och källrepresentation tillgänglig tills migrerade sidor passerar strukturella, visuella, tillgänglighets- och strukturerade utdatakontroller. Om en migrering misslyckas, återställ föregående versionsmappning istället för att platta till elementet till fritext, vilket skulle kasta bort den semantik versionshanteringen är avsedd att skydda.

Produktionsgranskningschecklista

Använd denna slutliga granskning efter prosa- och elementgenomgången:

• Kan varje icke-prosablocks syfte anges med ett verb?
• Söktes biblioteket efter det syftet och nära synonymer?
• Använder varje matchande syfte sitt typsatta element, även när en H2 och ett stycke skulle se likadana ut?
• Är varje återstående fritextavsnitt en del av artikelns löpande förklaring, analys, berättelse eller övergång?
• Följer attribut {nyckel=värde nyckel2="värde med mellanslag" .class}, med mellanslag citerade och endast deklarerade nycklar använda?
• Kartläggs den första brödtextrubriken till title och resten till content, om inte elementsidan deklarerar en annan mappning?
• Använder repeterbara barn ::objekt{nyckel=värde} … ::, med förälder- och objektattribut placerade på rätt nivå?
• Är interna länkar rotrelativa med inledande och avslutande snedstreck, externa länkar absoluta, och bildsökvägar inom den godkända bildroten?
• Finns metadatafält i frontmatter, aldrig som brödtextdirektiv, och är alla obligatoriska metadatavärden fullständiga?
• Kan samma kanoniska fält mappas utan förlust till Markdown, Hugo och WordPress?
• Bevarar någon definitionsändring gamla sidor eller introducerar en explicit version och migrering?

Denna sida är en förutsättning för varje enskild elementsida. Varje elementdefinition måste länka tillbaka till dessa basregler och sedan dokumentera endast sina syftesspecifika undantag: attribut som stöds, obligatoriska fält, åsidosättanden av brödtext- eller objektmappning, tillåten nästling, exakta plattformsnamn och versionshistorik. Om en elementsida är tyst gäller standardvärdena på denna sida.