Regler for innholdselementer: Når du skal bruke hver blokk

Hver side i SEO-spilleboken avhenger av ett skille: et innholdsstykke har et formål, mens overskriftsnivået og det visuelle utseendet kun er presentasjon. Disse skrivereglene for elementer gjør det skillet til en produksjonskontrakt. Følg dem før du bruker en komponent, konverterer en artikkel mellom publiseringssystemer, eller endrer et element som allerede finnes på publiserte sider.

Rask oversikt

• Sjekk elementbiblioteket etter formål før navn. Hvis et elements formål stemmer overens med jobben et avsnitt utfører, er det elementet obligatorisk.
• Bruk ren Markdown bare etter at du har bekreftet at ingen typede elementer representerer avsnittets formål. Fri tekst er en reserve, ikke en standard.
• Skriv hele artikkelen som ren tekst først. Bruk elementer i en separat topp-til-bunn strukturell gjennomgang, slik at komposisjon og oppmerking ikke konkurrerer om oppmerksomheten.
• Behandle Markdown-direktivet som kanonisk forfattet innhold. Hugo- og WordPress-rendere mapper de samme feltene og brødteksten til plattformspesifikk utdata.
• Hold eksisterende publiserte sider til betydningen de ble gjennomgått mot. En brytende definisjonsendring oppretter en ny versjon og en eksplisitt migrering; den omtolker aldri gammelt innhold i stillhet.

Den styrende prioriteringsregelen

Biblioteket må sjekkes etter hva et avsnitt gjør, ikke etter hva forfatteren tilfeldigvis kalte det. Navn varierer: én forfatter kan kalle en seksjon «Hva er churn?», en annen «Churn forklart», og en tredje «En arbeidsdefinisjon». Formålet deres er identisk, så alle tre kartlegges til det samme definisjonselementet.

Denne prioriteringen eksisterer fordi fri tekst og et typet element kan se identiske ut på skjermen samtidig som de oppfører seg helt forskjellig nedstrøms. En stilisert overskrift etterfulgt av et avsnitt kan ligne en definisjonsboks i nettleseren, men den bærer ingen komponentidentitet. Den kan ikke pålitelig produsere definisjonens strukturerte utdata, eksponere feltene for en annen renderer, beholde semantikken under migrering, eller bli funnet av en kvalitetssjekk som spør om siden inneholder en definisjon. Det typede elementet kartlegges til en komponent og en kjent dataform; visuelt lik fri tekst kartlegges til ingenting.

Regelen er derfor streng:

Før du skriver eller godkjenner en overskrift eller innholdsblokk, identifiser formålet. Hvis det formålet samsvarer med en elementdefinisjon, bruk elementet. Visuell likhet, en eksisterende H2, eller evnen til å uttrykke de samme ordene i et avsnitt gjør ikke fri tekst likeverdig.

Prioritering er semantisk snarere enn visuell. En side kan fortsatt inneholde vanlige overskrifter inni eller rundt et element når definisjonen tillater det, men overskriften erstatter aldri elementtypen.

Fri tekst versus et typet element

Bruk denne beslutningsstien inntil det delte diagrammet er tilgjengelig:

1. Angi avsnittets jobb i ett verb. Eksempler inkluderer definer, advar, oppsummer, sammenlign, bevis, instruer, eller inviter til handling. Dette forhindrer at overskriftsteksten maskerer det underliggende formålet.
2. Søk i biblioteket etter det formålet og dets synonymer. En forfatter som bare ser etter den bokstavelige overskriften «Hva er X?» kan gå glipp av et definisjonselement hvis side heter «Definisjonsboks».
3. Bruk det samsvarende elementet når det finnes. Ikke sammenlign utseende eller spør om Markdown kan etterligne designet; den registrerte oppførselen er den avgjørende faktoren.
4. Bruk fri tekst når ingen formål samsvarer. Dette er korrekt for sammenbindende forklaring, argumentasjon, analyse, narrativ kontekst og overganger som tilhører artikkelens hovedflyt og ikke krever distinkt komponentoppførsel.
5. Registrer et gjentatt gap. Hvis det samme uoppnådde formålet dukker opp på tvers av flere sider, foreslå et bibliotekelement i stedet for å finne opp et engangsdirektiv eller CSS-behandling i en artikkel.

Ren Markdown er genuint korrekt når ordene utgjør artikkelens sammenhengende resonnement og ikke trenger en uavhengig etikett, datakontrakt, interaksjon eller gjenbrukssti. For eksempel er to avsnitt som forklarer hvorfor en anbefaling følger av foregående bevis, normal prosa. Et kompakt sett med konklusjoner på toppen er ikke normal prosa bare fordi det kan skrives som punktlister; det har det anerkjente formålet til et oversikts- eller hovedpunkter-element.

Vanlige forvirringer som fører til feil oppmerking

Disse tilfellene er listet opp eksplisitt fordi de lett passerer visuell gjennomgang. Feilen blir synlig først når en annen renderer, validator, søkeindeks eller forbruker av strukturert utdata mottar siden.

Skillet mellom hovedpunkter og en rask oversikt er spesielt viktig. Bruk hovedpunkter når elementene er konklusjoner leseren bør huske, noe som ofte betyr at de bare kan skrives etter at artikkelen eksisterer. Bruk en oversikt når elementene orienterer leseren om omfang eller rekkefølge før lesing. Velg basert på den redaksjonelle jobben, selv om det gjeldende temaet får begge komponentene til å se like ut.

Direktiv- og attributtsyntaks

Den kanoniske Markdown-formen bruker en navngitt blokkdirektiv. Attributter følger direktivnavnet innenfor krøllparenteser:

:::element-navn{nøkkel=verdi nøkkel2="verdi med mellomrom" .klasse}
Brødtekstinnhold
:::

Attributter finnes for å bære små, stabile egenskaper som påvirker elementets betydning eller støttede presentasjon. Å holde dem maskinlesbare forhindrer forfattere i å skjule konfigurasjon i prosa. Bruk nøkkel=verdi for en verdi uten mellomrom og nøkkel2="verdi med mellomrom" når mellomrom er til stede. En uanført attributtverdi kan ikke inneholde mellomrom. En innledende prikk legger til en støttet klasse, som i .compact; det er ikke et sted å finne opp sidespesifikk styling.

Attributtnøkler er skrevet med små bokstaver og bruker den nøyaktige skrivemåten definert på elementsiden. Booleske og oppramsede verdier følger også den sidens kontrakt. Ikke opprett et attributt fordi en renderer tilfeldigvis tolererer det: et uerklært attributt har ingen kryssplattformgaranti.

Avsluttende :::-markører tilhører det ytre elementet. Hold dem på egne linjer slik at en tolk kan skille brødteksten fra neste avsnitt. Kodeeksempler som viser direktiver, må holdes innenfor kodeblokker med markører, slik de gjør på denne siden, slik at Hugo ikke tolker dem som innhold.

Standard brødtekstkartlegging

De fleste elementer trenger en kort tittel og en lengre brødtekst. Å kreve at forfattere gjentar disse som attributter ville gjort lang tekst vanskelig å redigere og lett å unnslippe feil, så brødteksten gir standardkartleggingen:

:::eksempel
## En konkret overskrift

Resten av brødteksten kan inneholde avsnitt, lister, lenker og annet innhold som er tillatt i henhold til elementdefinisjonen.
:::

Med mindre en elementside eksplisitt overstyrer regelen, kartlegges den første overskriften i brødteksten til title, og alt etter den overskriften kartlegges til content. Overskriftsmarkøren uttrykker kildens hierarki for redaktører; det kartlagte feltet lar hver plattform gjengi det passende semantiske overskriftsnivået i kontekst.

Bare den første brødtekstoverskriften får denne spesialbehandlingen. Senere overskrifter forblir en del av content. Hvis brødteksten ikke har noen overskrift, er title fraværende; det er kun gyldig når elementdefinisjonen markerer tittelen som valgfri. Hvis et element definerer navngitte spor eller en annen kartlegging, har elementets egen side forrang over denne standarden fordi renderen må vite nøyaktig hvor hvert fragment hører hjemme.

Nestede elementer

Noen elementer inneholder en gjentakbar liste der hver oppføring trenger egne attributter og en brødtekst, for eksempel trinn med identifikatorer, kort med etiketter, eller sjekklisteelementer med en starttilstand. Å flate ut disse oppføringene i én Markdown-liste ville miste deres individuelle felt, så nestede elementer bruker et eksplisitt elementdirektiv:

:::foreldre-element{variant=compact}
::element{nøkkel=verdi}
### Første elementtittel

Første elements forklaring.
::
::element{nøkkel2="verdi med mellomrom"}
### Andre elementtittel

Andre elements forklaring.
::
:::

Kontrakten er ::element{nøkkel=verdi} … ::: to kolon åpner hvert element, entallsnavnet er element, og to kolon lukker det. Foreldreelementet beholder sin tre-kolons avsluttende markør. Denne visuelle forskjellen er viktig fordi den gjør nesting utvetydig uten å stole på innrykk, som lett blir ødelagt ved kopiering og liming.

Hvert element bruker samme standard brødtekstkartlegging med mindre foreldreelementsiden sier noe annet: dens første overskrift blir det elementets title, og resten blir dets content. Sett attributter på elementet når de beskriver bare det elementet; sett dem på foreldreelementet når de påvirker samlingen som helhet.

Lenker, bilder og innebygde knapper

Bærbar kilde trenger forutsigbare stier. En relativ URL bør være relativ til siteroten, ikke til den gjeldende Markdown-filen, fordi samme kilde kan gjengis på en annen filsystemdybde i Hugo eller importeres til WordPress.

• Interne sidelenker bruker en innledende og avsluttende skråstrek, slik elementbiblioteket -lenken gjør. Ikke bruk ../, utelat den innledende skråstreken, eller hardkode produksjonsdomenet for en intern side.
• Eksterne lenker bruker en fullstendig https://-URL. Skjemaet er en del av destinasjonen og må ikke utledes av en renderer.
• Bildets kildefiler ligger under cdn-assets/seo-playbook/, og deres offentlige stier begynner på /cdn-assets/seo-playbook/. Legg til den godkjente gruppen og filnavnet bare etter at aktivaen eksisterer.
• Alternativ tekst beskriver informasjonen som formidles av et bilde, ikke filnavnet eller det dekorative utseendet. Et dekorativt bilde bruker en tom alternativ tekst, men den relevante elementsiden må eksplisitt tillate dekorasjon.
• En innebygd handlingsfremmende oppfordring bruker :button[Synlig etikett]{href="/mål/"}. Teksten i parentes er den tilgjengelige etiketten, og href følger samme regler for interne eller eksterne stier. Bruk en knapp bare for en genuin neste handling, ikke for å gjøre en vanlig referanselenke mer fremtredende.

Et bilde er innhold, ikke en omvei for å omgå uønsket layout. Hvis bildet inneholder essensielle etiketter, tall eller instruksjoner, gjenta den informasjonen i tilgjengelig tekst eller bruk et strukturert element som eksponerer den. Skjermbilde-fangstforespørsler forblir HTML-kommentarer inntil den navngitte aktivaen eksisterer; de er ikke publiserte bildereferanser og må sette screenshotsPending = true i frontmatter.

Frontmatter og brødtekstelementer har forskjellige jobber

Frontmatter beskriver dokumentet som et dokument. Brødtekstdirektiver beskriver meningsfulle blokker innenfor leseopplevelsen. Å holde disse lagene adskilt lar listesider, skjemaer, ruting og publiseringsverktøy lese metadata uten å tolke synlig prosa.

Metadataelementer lever derfor i frontmatter: sidetittel, beskrivelse, nøkkelord, publiserings- og oppdateringsdatoer, kanonisk- eller aliasinformasjon, eierskap, taksonomi, spilleboktilknytninger, og eventuelle skjemaorienterte samlinger som sidekontrakten plasserer der, for eksempel FAQ-oppføringer på akademisider. Disse feltene skrives aldri som :::-direktiver. En synlig blokk som gjentar noe metadata flytter ikke det autoritative feltet ut av frontmatter; den får sitt eget brødtekstelement bare når det har et separat leservendt formål.

Innholdselementer lever i brødteksten: definisjoner, advarsler, tips, oversikter, hovedpunkter, sjekklister, sammenligninger, bevisblokker, eksempler, trinn og handlingsfremmende oppfordringer. De er direktiver fordi deres plassering i fortellingen betyr noe. Å flytte en advarsel inn i frontmatter ville koble den fra avsnittet den kvalifiserer; å skjule metadata i et brødtekstdirektiv ville gjøre det umulig for dokumentnivåsystemer å finne det pålitelig.

Metadata er påkrevd som standard

Metadata driver ruter, forhåndsvisninger, oppdagelse, tilknytninger og strukturert utdata før noen leser brødteksten. Et utelatt felt kan derfor ødelegge forbrukere som aldri gjengir artikkelen. Av den grunn er hvert metadataelement påkrevd med mindre elementsiden eksplisitt sier at det er valgfritt.

Påkrevd betyr fylt ut med en gyldig verdi, ikke bare til stede som en tom streng eller tom samling. Ikke utled valgfrihet fra en annen sides utelatelse, og ikke legg inn plassholderverdier for å tilfredsstille validering. Hvis en påkrevd verdi ikke er kjent ennå, er siden ikke klar til å publiseres. Brødtekstelementer følger kravene til den relevante innleggstypen og elementsidene i stedet for denne metadata-standarden.

Skriv først, bruk elementer deretter

Elementvalg er en klassifiseringsoppgave, mens utkastskriving er en resonneringsoppgave. Å prøve å utføre begge setning for setning får forfatteren til å optimalisere for tidlig for komponentgrenser. Det vanlige resultatet er svakere overganger, grunne forklaringer tilpasset en boks, gjentatte overskrifter laget for å tilfredsstille oppmerking, og direktiver valgt fordi de er praktiske snarere enn fordi deres formål samsvarer.

Produksjon skjer derfor i to separate gjennomganger:

1. Skriv hele artikkelen som ren tekst. Fullfør argumentet, eksemplene, kvalifikasjonene, overgangene og konklusjonen. På dette stadiet kan overskrifter beskrive utkastets logikk, men de avgjør ikke den endelige elementtypen.
2. Bruk elementer i en separat topp-til-bunn-gjennomgang. For hver overskrift og blokk, angi formålet, sjekk biblioteket, pakk inn samsvarende seksjoner, legg til erklærte attributter, og bekreft brødtekstkartlegging og nesting.

Separasjonen forbedrer begge resultatene. Prosaen utvikler seg i henhold til leserens spørsmål i stedet for det gjeldende temaets boksstørrelser, mens oppmerkingsgjennomgangen kan sammenligne lignende blokker konsekvent på tvers av hele dokumentet. Det gjør også utelatelser synlige: en forfatter kan se at artikkelen inneholder en advarsel eller definisjon før de bestemmer seg for hvordan den skal kodes.

Etter den strukturelle gjennomgangen, les siden én gang uten å se på direktivnavnene. Elementer må støtte en sammenhengende artikkel, ikke gjøre den om til en stabel med frakoblede widgeter. Deretter inspiser kilden én gang uten å vurdere prosaen, og verifiser markører, attributter, nestede elementer, stier og påkrevd metadata.

Tre-notasjonsavtalen

Et element defineres én gang av dets formål, kanoniske felt, tillatte verdier, brødtekstkartlegging, tilgjengelighetsoppførsel, oppførsel for strukturert utdata og versjon. Den definisjonen er sannhetskilden. De tre plattformnotasjonene er tilpassninger til den, ikke tre uavhengige komponentdesign.

De representative formene forklarer kartleggingen; den individuelle elementsiden publiserer sitt eksakte støttede navn og felt. Forfattere jobber i notasjonen som kreves av deres publiseringsarbeidsflyt, men de omdøper ikke felt, legger ikke til plattformspesifikke betydninger, eller imiterer manuelt en annen renderers HTML.

Elementeieren vedlikeholder den kanoniske definisjonen og avgjør om en foreslått endring er kompatibel eller versjonert. Hugo- og WordPress-vedlikeholdere eier sine tilpassninger og tester dem mot delte testdata: samme tittel, innhold, attributter, elementer, lenker og tilgjengelighetsforventninger må overleve alle tre stiene. Redaksjonelle eiere verifiserer formål og eksempler. Ingen plattformvedlikeholder kan omdefinere den redaksjonelle betydningen lokalt; hvis en plattform ikke kan uttrykke kontrakten, er det en tilpassningsfeil eller et forslag til kontraktsendring.

Denne modellen tillater presentasjon å variere der plattformer krever det, samtidig som semantikken holdes stabil. Hugo kan gjengi HTML på serversiden og WordPress kan lagre en blokkommentar, men en advarsel forblir en advarsel, et sjekklisteelement forblir et element, og de samme påkrevde feltene forblir tilgjengelige nedstrøms.

Versjonering av publiserte elementer

Publisert innhold ble gjennomgått mot elementbetydningen som eksisterte på publiseringstidspunktet. Å stille endre den betydningen kan endre advarsler, strukturerte data, tilgjengelighet eller import uten at en redaktør rører siden. Versjonering beskytter den redaksjonelle godkjenningen.

Bruk følgende endringspolicy:

• Kompatibel rendererendring: En visuell forbedring, ytelsesforbedring eller feilretting som bevarer formål, felt, aksepterte verdier, brødtekstkartlegging og utdatabetydning kan leveres innenfor gjeldende versjon. Eksisterende sider mottar den gjennom renderen.
• Kompatibel additiv endring: Et nytt valgfritt attributt kan bli med i gjeldende versjon bare når dets fravær bevarer eksisterende utdata og hver tilpassning trygt kan ignorere eller støtte det. Definisjonen og plattformtestene endres sammen.
• Brytende endring: Et omdøpt eller fjernet felt, et nytt påkrevd felt, endret brødtekstkartlegging, endret formål, endret standard med semantisk effekt, eller inkompatibel nestet-elementstruktur oppretter en ny hovedversjon av elementet.
• Avskrivning: Den gamle versjonen forblir gjengivbar for publiserte sider. Elementsiden identifiserer erstatningen og migreringsstien; nye sider bruker gjeldende versjon.
• Migrering: En innholdsmigrering er eksplisitt, avgrenset, forhåndsvist på tvers av Markdown, Hugo og WordPress, og redaksjonelt validert før publisering. Registrer hvilke sider som ble endret og hvorfor. Ikke la en renderer gjette hvordan gammel kilde skal omtolkes.

Når ingen versjon er skrevet i kilden, bruker elementet grunnversjonen definert da denne kontrakten ble tatt i bruk. Den implisitte grunnversjonen må forbli stabil. Nye hovedversjoner identifiserer seg selv ved hjelp av versjonsmekanismen som er erklært på elementsiden; de omformålbruker ikke den versjonsløse syntaksen.

Tilbakerulling er også viktig. Hold den forrige renderen og kilde-representasjonen tilgjengelig inntil migrerte sider består strukturelle, visuelle, tilgjengelighets- og strukturerte utdatasjekker. Hvis en migrering mislykkes, gjenopprett den forrige versjonskartleggingen i stedet for å flate ut elementet til fri tekst, noe som ville kaste bort semantikken versjonering er ment å beskytte.

Produksjonsgjennomgangsliste

Bruk denne endelige gjennomgangen etter prosagjennomgangen og elementgjennomgangen:

• Kan ethvert ikke-prosaavsnitts formål angis med ett verb?
• Ble biblioteket søkt etter det formålet og nære synonymer?
• Bruker hvert samsvarende formål sitt typed element, selv når en H2 og et avsnitt ville sett like ut?
• Er ethvert gjenværende fritekstavsnitt en del av artikkelens sammenhengende forklaring, analyse, narrativ eller overgang?
• Følger attributter {nøkkel=verdi nøkkel2="verdi med mellomrom" .klasse}, med mellomrom anført og bare erklærte nøkler brukt?
• Kartlegges den første brødtekstoverskriften til title og resten til content, med mindre elementsiden erklærer en annen kartlegging?
• Bruker gjentakbare barn ::element{nøkkel=verdi} … ::, med foreldre- og elementattributter plassert på riktig nivå?
• Er interne lenker rotrelative med innledende og avsluttende skråstreker, eksterne lenker absolutte, og bildestier innenfor den godkjente bilderoten?
• Er metadatafelt i frontmatter, aldri brødtekstdirektiver, og er alle påkrevde metadataverdier fullstendige?
• Kan de samme kanoniske feltene kartlegges uten tap til Markdown, Hugo og WordPress?
• Bevarer enhver definisjonsendring gamle sider eller introduserer den en eksplisitt versjon og migrering?

Denne siden er en forutsetning for hver individuelle elementside. Hver elementdefinisjon må lenke tilbake til disse grunnreglene, og deretter dokumentere bare sine formålsspesifikke unntak: støttede attributter, påkrevde felt, overstyringer av brødtekst- eller elementkartlegging, tillatt nesting, eksakte plattformnavn og versjonshistorikk. Hvis en elementside er taus, gjelder standardene på denne siden.