Content-element-regler: Hvornår skal hvilken blok bruges

Hver side i SEO-playbooken afhænger af én skelnen: et stykke indhold har et formål, mens dets overskriftniveau og visuelle fremtoning kun er præsentation. Disse element-skriveregler omsætter den skelnen til en produktionskontrakt. Følg dem, før du anvender en komponent, konverterer en artikel mellem publiceringssystemer eller ændrer et element, der allerede findes på publicerede sider.

Hurtigt overblik

• Tjek elementbiblioteket efter formål før navn. Hvis et elements formål matcher det job, et afsnit udfører, er det element obligatorisk.
• Brug almindelig Markdown kun efter at have bekræftet, at intet typebestemt element repræsenterer afsnittets formål. Fri tekst er en reserve, ikke en standard.
• Skriv hele artiklen som almindelig tekst først. Anvend elementer i en separat top-til-bund strukturel gennemgang, så komposition og markup ikke konkurrerer om opmærksomheden.
• Behandl Markdown-direktivet som kanonisk forfatterskabt indhold. Hugo- og WordPress-renderere kortlægger de samme felter og brødtekst til platformspecifikt output.
• Hold eksisterende publicerede sider på den betydning, de blev gennemgået med. En brydende definitionsændring skaber en ny version og en eksplicit migrering; den fortolker aldrig gammelt indhold stille og roligt om.

Den styrende forrangsmodel

Biblioteket skal tjekkes efter hvad et afsnit gør, ikke efter hvad skribenten tilfældigvis kaldte det. Navne varierer: én skribent kan kalde et afsnit “Hvad er churn?”, en anden “Churn forklaret”, og en tredje “En arbejdsdefinition”. Deres formål er identisk, så alle tre kortlægges til det samme definitionselement.

Denne forrang eksisterer, fordi fri tekst og et typebestemt element kan se identiske ud på skærmen, mens de opfører sig fuldstændigt forskelligt downstream. En styleset overskrift efterfulgt af et afsnit kan ligne en definitionsboks i browseren, men den har ingen komponentidentitet. Den kan ikke pålideligt producere definitionens strukturerede output, eksponere dens felter til en anden renderer, bevare dens semantik under migrering eller findes af en kvalitetskontrol, der spørger, om siden indeholder en definition. Det typebestemte element kortlægges til en komponent og en kendt dataform; visuelt lignende fri tekst kortlægges til intet.

Reglen er derfor streng:

Før du skriver eller godkender en overskrift eller indholdsblok, identificér dens formål. Hvis formålet matcher en elementdefinition, brug elementet. Visuel lighed, en eksisterende H2 eller evnen til at udtrykke de samme ord i et afsnit gør ikke fri tekst til et alternativ.

Forrang er semantisk snarere end visuel. En side kan stadig indeholde almindelige overskrifter indeni eller omkring et element, når dets definition tillader det, men overskriften erstatter aldrig elementtypen.

Fri tekst versus et typebestemt element

Brug denne beslutningssti, indtil det delte diagram er tilgængeligt:

1. Angiv afsnittets opgave i ét udsagnsord. Eksempler omfatter definere, advare, opsummere, sammenligne, bevise, instruere eller invitere til handling. Dette forhindrer, at overskriftsteksten skjuler det underliggende formål.
2. Søg i biblioteket efter det formål og dets synonymer. En skribent, der kun leder efter den bogstavelige overskrift “Hvad er X?”, kan overse et definitionselement, hvis side hedder “Definitionsboks”.
3. Brug det matchende element, når et findes. Sammenlign ikke udseender, eller spørg om Markdown kunne efterligne designet; den registrerede adfærd er den afgørende faktor.
4. Brug fri tekst, når intet formål matcher. Dette er korrekt til forbindende forklaring, argumentation, analyse, narrativ kontekst og overgange, der hører til artiklens hovedflow og ikke kræver en særskilt komponentadfærd.
5. Registrér et gentaget hul. Hvis det samme umatchede formål optræder på tværs af flere sider, foreslå et bibliotekselement i stedet for at opfinde et engangsdirektiv eller en CSS-behandling i en artikel.

Almindelig Markdown er ægte korrekt, når ordene udgør artiklens sammenhængende ræsonnement og ikke har brug for en uafhængig etiket, datakontrakt, interaktion eller genbrugssti. For eksempel er to afsnit, der forklarer, hvorfor en anbefaling følger af den foregående dokumentation, normal prosa. Et kompakt sæt konklusioner øverst er ikke normal prosa, blot fordi det kan skrives som punkter; det har det anerkendte formål som et overbliks- eller pointerelement.

Almindelige forvirringer, der fører til forkert markup

Disse tilfælde er oplistet eksplicit, fordi de let består et visuelt tjek. Fejlen bliver først synlig, når en anden renderer, validator, søgeindeks eller forbruger af struktureret output modtager siden.

Skelnen mellem vigtige pointer og et hurtigt overblik er særlig vigtig. Brug pointer, når elementerne er konklusioner, læseren bør huske, hvilket betyder, at de ofte kun kan skrives, efter artiklen eksisterer. Brug et overblik, når elementerne orienterer læseren om omfang eller rækkefølge før læsning. Vælg efter dette redaktionelle job, selvom det aktuelle tema får begge komponenter til at se ens ud.

Direktiv- og attributsyntaks

Den kanoniske Markdown-form bruger en navngivet blokdirektiv. Attributter følger direktivnavnet inde i krøllede parenteser:

:::element-navn{nøgle=værdi nøgle2="værdi med mellemrum" .class}
Brødtekstindhold
:::

Attributter findes for at bære små, stabile egenskaber, der påvirker elementets betydning eller understøttede præsentation. At holde dem maskinlæselige forhindrer skribenter i at skjule konfiguration i prosa. Brug nøgle=værdi til en værdi uden mellemrum og nøgle2="værdi med mellemrum", når der er mellemrum. En uanført attributværdi må ikke indeholde mellemrum. Et indledende punktum tilføjer en understøttet klasse, som i .compact; det er ikke et sted at opfinde sidespecifik styling.

Attributnøgler er med små bogstaver og bruger den nøjagtige stavemåde defineret på elementsiden. Booleske og opregnede værdier følger også den sides kontrakt. Opret ikke en attribut, fordi en renderer tilfældigvis tolererer den: en uerklæret attribut har ingen krydsplatformsgaranti.

Afsluttende :::-afgrænsere tilhører det ydre element. Hold dem på deres egne linjer, så en parser kan skelne brødteksten fra det næste afsnit. Kodeeksempler, der demonstrerer direktiver, skal forblive inden for afgrænsede kodeblokke, som de gør på denne side, så Hugo ikke fortolker dem som indhold.

Standard brødtekstkortlægning

De fleste elementer har brug for en kort titel og en længere brødtekst. At kræve, at forfattere gentager disse som attributter, ville gøre lang tekst svær at redigere og let at escape forkert, så brødteksten leverer standardkortlægningen:

:::eksempel
## En konkret overskrift

Resten af brødteksten kan indeholde afsnit, lister, links og andet indhold, der er tilladt af elementdefinitionen.
:::

Medmindre en elementside eksplicit tilsidesætter reglen, kortlægges den første overskrift i brødteksten til title, og alt efter den overskrift kortlægges til content. Overskriftsmarkøren udtrykker kildehierarki for redaktører; det kortlagte felt lader hver platform gengive det passende semantiske overskriftniveau i kontekst.

Kun den første brødtekstoverskrift modtager denne særbehandling. Senere overskrifter forbliver en del af content. Hvis brødteksten ikke har nogen overskrift, er title fraværende; det er kun gyldigt, når elementdefinitionen angiver sin titel som valgfri. Hvis et element definerer navngivne slots eller en anden kortlægning, har dets egen side forrang over denne standard, fordi renderen skal vide præcis, hvor hvert fragment hører til.

Indlejrede elementer

Nogle elementer indeholder en gentagelig liste, hvis poster hver har brug for attributter og en brødtekst, såsom trin med identifikatorer, kort med etiketter eller checklisteposter med en starttilstand. At flade disse poster ud i én Markdown-liste ville miste deres individuelle felter, så indlejrede poster bruger et eksplicit item-direktiv:

:::overordnet-element{variant=compact}
::item{nøgle=værdi}
### Første punkts titel

Det første punkts forklaring.
::
::item{nøgle2="værdi med mellemrum"}
### Anden punkts titel

Det andet punkts forklaring.
::
:::

Kontrakten er ::item{nøgle=værdi} … ::: to koloner åbner hvert punkt, entalsnavnet er item, og to koloner lukker det. Det overordnede element beholder sin tre-kolomers afsluttende afgrænser. Denne visuelle forskel betyder noget, fordi den gør indlejring utvetydig uden at stole på indrykning, som let beskadiges ved kopiering og indsættelse.

Hvert punkt anvender den samme standard brødtekstkortlægning, medmindre det overordnede elementside siger andet: dets første overskrift bliver det pågældende punkts title, og resten bliver dets content. Sæt attributter på punktet, når de kun beskriver det punkt; sæt dem på det overordnede element, når de påvirker samlingen som helhed.

Links, billeder og inline-knapper

Bærbar kilde har brug for forudsigelige stier. En relativ URL bør være relativ i forhold til site-roden, ikke til den aktuelle Markdown-fil, fordi den samme kilde kan gengives i en anden filsystemdybde i Hugo eller importeres til WordPress.

• Interne sidelinks bruger et indledende og afsluttende skråstreg, som elementbiblioteket -linket gør. Brug ikke ../, udelad ikke den indledende skråstreg, eller hardkode produktionsdomænet for en intern side.
• Eksterne links bruger en komplet https:// URL. Protokollen er en del af destinationen og må ikke udledes af en renderer.
• Billedkildefiler ligger under cdn-assets/seo-playbook/, og deres offentlige stier begynder med /cdn-assets/seo-playbook/. Tilføj den godkendte gruppe og filnavn først, efter aktivet eksisterer.
• Alternativ tekst beskriver den information, et billede formidler, ikke dets filnavn eller dekorative udseende. Et dekorativt billede bruger en tom alternativ tekst, men den relevante elementside skal eksplicit tillade dekoration.
• Et inline-handlingskald bruger :button[Synlig etiket]{href="/target/"}. Den kantede parentes-tekst er den tilgængelige etiket, og href følger de samme interne eller eksterne stiregler. Brug en knap kun til en ægte næste handling, ikke for at gøre et almindeligt referencelink mere fremtrædende.

Et billede er indhold, ikke en løsning på ikke-understøttet layout. Hvis billedet indeholder væsentlige etiketter, tal eller instruktioner, gentag den information i tilgængelig tekst eller brug et struktureret element, der eksponerer det. Skærmbillede-anmodninger forbliver HTML-kommentarer, indtil det navngivne aktiv eksisterer; de er ikke publicerede billedreferencer og skal sætte screenshotsPending = true i frontmatter.

Frontmatter og brødtekst-elementer har forskellige opgaver

Frontmatter beskriver dokumentet som dokument. Brødtekstdirektiver beskriver meningsfulde blokke i læseoplevelsen. At holde disse lag adskilt lader liste-sider, skemaer, routing og publiceringsværktøjer læse metadata uden at parse synlig prosa.

Metadata-elementer bor derfor i frontmatter: sidetitel, beskrivelse, nøgleord, publicerings- og opdateringsdatoer, kanonisk- eller alias-information, ejerskab, taksonomi, playbook-tilknytninger og eventuelle skemaorienterede samlinger, som sidekontrakten placerer der, såsom FAQ-poster på akademisider. Disse felter skrives aldrig som :::-direktiver. En synlig blok, der gentager nogle metadata, flytter ikke det autoritative felt ud af frontmatter; den modtager sit eget brødtekstelement kun, når det har et separat læservendt formål.

Indholdselementer bor i brødteksten: definitioner, advarsler, tips, overblik, pointer, checklister, sammenligninger, evidensblokke, eksempler, trin og handlingskald. De er direktiver, fordi deres placering i fortællingen betyder noget. At flytte en advarsel ind i frontmatter ville afkoble den fra det afsnit, den kvalificerer; at gemme metadata i et brødtekstdirektiv ville gøre det umuligt for dokumentniveausystemer at finde det pålideligt.

Metadata er som udgangspunkt påkrævet

Metadata driver ruter, forhåndsvisninger, opdagelse, tilknytninger og struktureret output, før nogen læser brødteksten. Et udeladt felt kan derfor bryde forbrugere, der aldrig gengiver artiklen. Af den grund er hvert metadataelement påkrævet, medmindre dets elementside eksplicit siger, at det er valgfrit.

Påkrævet betyder udfyldt med en gyldig værdi, ikke blot til stede som en tom streng eller tom samling. Slut ikke valgfrihed ud fra en anden sides udeladelse, og tilføj ikke pladsholderværdier for at opfylde validering. Hvis en påkrævet værdi endnu ikke er kendt, er siden ikke klar til publicering. Brødtekstelementer følger kravene i de relevante posttype- og elementsider snarere end denne metadata-standard.

Skriv først, anvend elementer bagefter

Elementvalg er en klassificeringsopgave, mens udkastskrivning er en ræsonnementsopgave. At forsøge at udføre begge sætning for sætning får skribenten til at optimere for tidligt for komponentgrænser. Det sædvanlige resultat er svagere overgange, overfladiske forklaringer tilpasset en boks, gentagne overskrifter skabt for at tilfredsstille markup og direktiver valgt, fordi de er bekvemme snarere end fordi deres formål matcher.

Produktion foregår derfor i to adskilte gennemgange:

1. Skriv hele artiklen som almindelig tekst. Gennemfør argumentet, eksempler, kvalifikationer, overgange og konklusion. På dette tidspunkt kan overskrifter beskrive udkastets logik, men de fastlægger ikke den endelige elementtype.
2. Anvend elementer i en separat top-til-bund gennemgang. For hver overskrift og blok, angiv dens formål, tjek biblioteket, indpak matchende sektioner, tilføj erklærede attributter, og bekræft brødtekstkortlægning og indlejring.

Adskillelsen forbedrer begge output. Prosaen udvikler sig efter læserens spørgsmål i stedet for det aktuelle temas bokstørrelser, mens markup-gennemgangen kan sammenligne lignende blokke konsekvent på tværs af hele dokumentet. Det gør også udeladelser synlige: en skribent kan se, at artiklen indeholder en advarsel eller definition, før hun beslutter, hvordan den skal kodes.

Efter den strukturelle gennemgang, læs siden én gang uden at se på direktivnavnene. Elementer skal understøtte en sammenhængende artikel, ikke gøre den til en stak af uforbundne widgets. Inspicér derefter kilden én gang uden at bedømme prosaen, og verificér afgrænsere, attributter, indlejrede elementer, stier og påkrævede metadata.

Tre-notationskontrakten

Et element defineres én gang ved sit formål, kanoniske felter, tilladte værdier, brødtekstkortlægning, tilgængelighedsadfærd, struktureret-output-adfærd og version. Den definition er sandhedskilden. De tre platformnotationer er adaptere til den, ikke tre uafhængige komponentdesigns.

De repræsentative former forklarer kortlægningen; den enkelte elementside publicerer sit nøjagtige understøttede navn og felter. Forfattere arbejder i den notation, der kræves af deres publiceringsworkflow, men de omdøber ikke felter, tilføjer ikke platformspecifikke betydninger eller efterligner manuelt en anden renderers HTML.

Elementejeren vedligeholder den kanoniske definition og afgør, om en foreslået ændring er kompatibel eller versionsbestemt. Hugo- og WordPress-vedligeholdere ejer deres adaptere og tester dem mod delte fixtures: den samme titel, indhold, attributter, elementer, links og tilgængelighedsforventninger skal overleve alle tre stier. Redaktionelle ejere verificerer formål og eksempler. Ingen platformvedligeholder må omdefinere den redaktionelle betydning lokalt; hvis en platform ikke kan udtrykke kontrakten, er det en adapterfejl eller en foreslået kontraktændring.

Denne model tillader, at præsentation kan variere, hvor platforme kræver det, mens semantik forbliver stabil. Hugo kan gengive serverside-HTML og WordPress kan gemme en blokkommentar, men en advarsel forbliver en advarsel, et checklistepunkt forbliver et punkt, og de samme påkrævede felter forbliver tilgængelige downstream.

Versionering af publicerede elementer

Publiceret indhold blev gennemgået mod den elementbetydning, der eksisterede på publiceringstidspunktet. Stille og roligt at ændre den betydning kan ændre advarsler, strukturerede data, tilgængelighed eller importer uden at en redaktør rører siden. Versionering beskytter den redaktionelle godkendelse.

Brug følgende ændringspolitik:

• Kompatibel renderer-ændring: En visuel forbedring, præstationsoptimering eller fejlrettelse, der bevarer formål, felter, accepterede værdier, brødtekstkortlægning og outputbetydning, kan sendes inden for den aktuelle version. Eksisterende sider modtager den gennem renderen.
• Kompatibel tilføjende ændring: En ny valgfri attribut kan tilføjes den aktuelle version, kun når dens fravær bevarer eksisterende output, og hver adapter sikkert kan ignorere eller understøtte den. Definitionen og platformtestene ændres sammen.
• Brydende ændring: Et omdøbt eller fjernet felt, et nyt påkrævet felt, ændret brødtekstkortlægning, ændret formål, ændret standard med semantisk effekt eller ukompatibel indlejret elementstruktur skaber en ny større elementversion.
• Udfasning: Den gamle version forbliver gengivelsesbar for publicerede sider. Dets elementside identificerer erstatningen og migrationsstien; nye sider bruger den aktuelle version.
• Migrering: En indholdsmigrering er eksplicit, afgrænset, forhåndsvist på tværs af Markdown, Hugo og WordPress, og redaktionelt valideret før publicering. Registrér hvilke sider der er ændret og hvorfor. Lad ikke en renderer gætte, hvordan gammel kilde skal genfortolkes.

Når ingen version er skrevet i kilden, bruger elementet den grundlæggende version defineret, da denne kontrakt blev vedtaget. Den implicitte grundlæggende version skal forblive stabil. Nye større versioner identificerer sig selv ved hjælp af versionsmekanismen erklæret på elementsiden; de genbruger ikke den versionsløse syntaks.

Tilbagerulning betyder også noget. Behold den forrige renderer og kilde-repræsentation tilgængelig, indtil migrerede sider består strukturelle, visuelle, tilgængeligheds- og struktureret-output-kontroller. Hvis en migrering fejler, gendan den forrige versionskortlægning i stedet for at flade elementet ud til fri tekst, hvilket ville kassere den semantik, versionering er beregnet til at beskytte.

Produktionsgennemgangs-tjekliste

Brug denne afsluttende gennemgang efter prose-gennemgangen og element-gennemgangen:

• Kan hver ikke-prosa-bloks formål angives med ét udsagnsord?
• Blev biblioteket søgt efter det formål og tætte synonymer?
• Bruger hvert matchende formål sit typebestemte element, selv når en H2 og et afsnit ville se ens ud?
• Er hvert tilbageværende frit-tekst-afsnit en del af artiklens sammenhængende forklaring, analyse, fortælling eller overgang?
• Følger attributter {nøgle=værdi nøgle2="værdi med mellemrum" .class}, med mellemrum anført og kun erklærede nøgler brugt?
• Kortlægges den første brødtekstoverskrift til title og resten til content, medmindre elementsiden erklærer en anden kortlægning?
• Bruger gentagelige børn ::item{nøgle=værdi} … ::, med overordnede og item-attributter placeret på det korrekte niveau?
• Er interne links rod-relative med indledende og afsluttende skråstreger, eksterne links absolutte, og billedstier inden for den godkendte billedrod?
• Er metadata-felter i frontmatter, aldrig brødtekstdirektiver, og er alle påkrævede metadata-værdier komplette?
• Kan de samme kanoniske felter kortlægges uden tab til Markdown, Hugo og WordPress?
• Bevarer enhver definitionsændring gamle sider eller introducerer den en eksplicit version og migrering?

Denne side er en forudsætning for hver enkelt elementside. Hver elementdefinition skal linke tilbage til disse grundlæggende regler og derefter kun dokumentere sine formålsspecifikke undtagelser: understøttede attributter, påkrævede felter, tilsidesættelser af brødtekst- eller item-kortlægning, tilladt indlejring, nøjagtige platformnavne og versionshistorik. Hvis en elementside er tavs, gælder standarderne på denne side.