Regels voor content-elementen: wanneer gebruik je welk blok

Elke pagina in het SEO-playbook hangt af van één onderscheid: een stuk content heeft een doel, terwijl het kopniveau en de visuele verschijning slechts presentatie zijn. Deze schrijfregels voor elementen maken van dat onderscheid een productiecontract. Volg ze voordat je een component toepast, een artikel tussen publicatiesystemen converteert of een element wijzigt dat al op gepubliceerde pagina’s voorkomt.

Snel overzicht

• Controleer de elementenbibliotheek op doel vóór naam. Als het doel van een element overeenkomt met de taak die een sectie uitvoert, is dat element verplicht.
• Gebruik gewone Markdown pas nadat je hebt bevestigd dat er geen getypeerd element de bedoeling van de passage vertegenwoordigt. Vrije tekst is een terugvaloptie, geen standaard.
• Schrijf het volledige artikel eerst als platte tekst. Pas elementen toe in een aparte structurele doorgang van boven naar beneden, zodat compositie en opmaak niet om aandacht concurreren.
• Beschouw de Markdown-richtlijn als de canonieke auteursinhoud. Hugo- en WordPress-renderers wijzen dezelfde velden en body toe aan platformspecifieke uitvoer.
• Houd bestaande gepubliceerde pagina’s op de betekenis waarop ze zijn beoordeeld. Een baanbrekende definitiewijziging creëert een nieuwe versie en een expliciete migratie; het herinterpreteert nooit stilletjes oude content.

De heersende prioriteitsregel

De bibliotheek moet worden gecontroleerd op basis van wat een passage doet, niet op basis van hoe de schrijver het toevallig heeft genoemd. Namen variëren: de ene schrijver noemt een sectie ‘Wat is churn?’, een ander ‘Churn uitgelegd’ en een derde ‘Een werkdefinitie’. Hun doel is identiek, dus alle drie wijzen ze toe aan hetzelfde definitie-element.

Deze prioriteit bestaat omdat vrije tekst en een getypeerd element er op het scherm identiek uit kunnen zien terwijl ze zich stroomafwaarts heel anders gedragen. Een opgemaakte kop gevolgd door een alinea lijkt misschien op een definitiekader in de browser, maar draagt geen componentidentiteit. Het kan niet betrouwbaar de gestructureerde uitvoer van de definitie produceren, de velden ervan blootstellen aan een andere renderer, de semantiek behouden tijdens migratie of worden gevonden door een kwaliteitscontrole die vraagt of de pagina een definitie bevat. Het getypeerde element wijst toe aan een component en een bekende gegevensvorm; visueel gelijkende vrije tekst wijst toe aan niets.

De regel is daarom streng:

Voordat je een kop of contentblok schrijft of goedkeurt, identificeer het doel ervan. Als dat doel overeenkomt met een elementdefinitie, gebruik dan het element. Visuele gelijkenis, een bestaande H2 of de mogelijkheid om dezelfde woorden in een alinea uit te drukken maakt vrije tekst niet gelijkwaardig.

Prioriteit is semantisch in plaats van visueel. Een pagina kan nog steeds gewone koppen bevatten in of rond een element wanneer de definitie dit toestaat, maar de kop vervangt nooit het elementtype.

Vrije tekst versus een getypeerd element

Gebruik dit beslissingspad totdat het gedeelde diagram beschikbaar is:

1. Formuleer de taak van de passage in één werkwoord. Voorbeelden zijn definiëren, waarschuwen, samenvatten, vergelijken, bewijzen, instrueren of tot actie aanzetten. Dit voorkomt dat de koptekst het onderliggende doel verhult.
2. Doorzoek de bibliotheek op dat doel en synoniemen daarvan. Een schrijver die alleen zoekt naar de letterlijke kop ‘Wat is X?’ kan een definitie-element missen waarvan de pagina ‘Definitiekader’ heet.
3. Gebruik het overeenkomende element wanneer dat bestaat. Vergelijk geen verschijningen of vraag of Markdown het ontwerp zou kunnen nabootsen; het geregistreerde gedrag is de beslissende factor.
4. Gebruik vrije tekst wanneer geen doel overeenkomt. Dit is correct voor verbindende uitleg, argumentatie, analyse, narratieve context en overgangen die thuishoren in de hoofdstroom van het artikel en geen apart componentengedrag vereisen.
5. Leg een herhaalde lacune vast. Als hetzelfde niet-overeenkomende doel op meerdere pagina’s voorkomt, stel dan een bibliotheekelement voor in plaats van een eenmalige richtlijn of CSS-behandeling in een artikel te verzinnen.

Gewone Markdown is echt correct wanneer de woorden de doorlopende redenering van het artikel vormen en geen onafhankelijk label, gegevenscontract, interactie of herbruikbaar pad nodig hebben. Twee alinea’s die uitleggen waarom een aanbeveling volgt uit het voorgaande bewijs zijn bijvoorbeeld normale proza. Een compacte set conclusies bovenaan is niet normaal proza alleen omdat het als opsommingstekens kan worden geschreven; het heeft het erkende doel van een overzichts- of conclusie-element.

Veelvoorkomende verwarringen die onjuiste opmaak veroorzaken

Deze gevallen worden expliciet vermeld omdat ze een visuele beoordeling gemakkelijk doorstaan. De fout wordt pas zichtbaar wanneer een andere renderer, validator, zoekindex of gestructureerde-uitvoerconsument de pagina ontvangt.

Het onderscheid tussen belangrijkste conclusies en een snel overzicht is bijzonder belangrijk. Gebruik conclusies wanneer de punten inzichten zijn die de lezer moet onthouden, wat betekent dat ze vaak pas geschreven kunnen worden nadat het artikel bestaat. Gebruik een overzicht wanneer de punten de lezer oriënteren op reikwijdte of volgorde vóór het lezen. Kies op basis van die redactionele taak, zelfs als het huidige thema beide componenten er hetzelfde uit laat zien.

Richtlijn- en attribuutsyntaxis

De canonieke Markdown-vorm gebruikt een benoemde blokrichtlijn. Attributen volgen de richtlijnnaam tussen accolades:

:::element-naam{sleutel=waarde sleut2="waarde met spaties" .class}
Body-inhoud
:::

Attributen bestaan om kleine, stabiele eigenschappen te dragen die de betekenis of ondersteunde presentatie van het element beïnvloeden. Door ze machinaal leesbaar te houden, wordt voorkomen dat schrijvers configuratie in proza verbergen. Gebruik sleutel=waarde voor een waarde zonder spaties en sleutel2="waarde met spaties" wanneer er spaties zijn. Een niet-gequote attribuutwaarde mag geen spaties bevatten. Een leidende punt voegt een ondersteunde klasse toe, zoals in .compact; het is geen plaats om paginaspecifieke styling te verzinnen.

Attribuutsleutels zijn in kleine letters en gebruiken de exacte spelling zoals gedefinieerd op de elementpagina. Booleaanse en opgesomde waarden volgen ook het contract van die pagina. Maak geen attribuut aan omdat een renderer het toevallig tolereert: een niet-gedeclareerd attribuut heeft geen cross-platform garantie.

Afsluitende :::-fences horen bij het buitenste element. Houd ze op aparte regels, zodat een parser de body van de volgende alinea kan onderscheiden. Codevoorbeelden die richtlijnen demonstreren, moeten binnen omsloten codeblokken blijven, zoals op deze pagina, zodat Hugo ze niet als content interpreteert.

Standaard body-toewijzing

De meeste elementen hebben een korte titel en een langere body nodig. Door auteurs te verplichten deze als attributen te herhalen, zou lange tekst moeilijk te bewerken en gemakkelijk onjuist te escapen zijn, dus de body biedt de standaardtoewijzing:

:::voorbeeld
## Een concrete kop

De rest van de body kan alinea's, lijsten, links en andere content bevatten die is toegestaan door de elementdefinitie.
:::

Tenzij een elementpagina de regel expliciet overschrijft, wordt de eerste kop in de body toegewezen aan title, en alles na die kop aan content. De kopmarkering geeft bronhiërarchie weer voor redacteuren; het toegewezen veld stelt elk platform in staat om het juiste semantische kopniveau in context weer te geven.

Alleen de eerste body-kop krijgt deze speciale behandeling. Latere koppen blijven onderdeel van content. Als de body geen kop heeft, is title afwezig; dat is alleen geldig wanneer de elementdefinitie de titel als optioneel markeert. Als een element benoemde slots of een andere toewijzing definieert, heeft de eigen pagina voorrang op deze standaard, omdat de renderer precies moet weten waar elk fragment thuishoort.

Geneste items

Sommige elementen bevatten een herhaalbare lijst waarvan de items elk attributen en een body nodig hebben, zoals stappen met id’s, kaarten met labels of checklistitems met een begintoestand. Deze items plat in één Markdown-lijst zetten zou hun individuele velden verliezen, dus geneste items gebruiken een expliciete itemrichtlijn:

:::bovenliggend-element{variant=compact}
::item{sleutel=waarde}
### Titel eerste item

Uitleg van het eerste item.
::
::item{sleutel2="waarde met spaties"}
### Titel tweede item

Uitleg van het tweede item.
::
:::

Het contract is ::item{sleutel=waarde} … ::: twee dubbele punten openen elk item, de enkelvoudige naam is item, en twee dubbele punten sluiten het. Het bovenliggende element behoudt zijn drie-dubbele-punten afsluitfence. Dit visuele verschil is belangrijk omdat het nesten ondubbelzinnig maakt zonder te vertrouwen op inspringing, die gemakkelijk beschadigd raakt door kopiëren en plakken.

Elk item past dezelfde standaard body-toewijzing toe, tenzij de bovenliggende elementpagina iets anders zegt: de eerste kop wordt de title van dat item, en de rest wordt de content ervan. Plaats attributen op het item wanneer ze alleen dat item beschrijven; plaats ze op het bovenliggende element wanneer ze de verzameling als geheel beïnvloeden.

Links, afbeeldingen en inline-knoppen

Draagbare bron heeft voorspelbare paden nodig. Een relatief URL moet relatief zijn ten opzichte van de site-root, niet ten opzichte van het huidige Markdown-bestand, omdat dezelfde bron op een andere bestandssysteemdiepte in Hugo kan worden weergegeven of in WordPress kan worden geïmporteerd.

• Interne paginalinks gebruiken een leidende en afsluitende schuine streep, zoals de elementenbibliotheek -link doet. Gebruik geen ../, laat de leidende schuine streep niet weg en hardcode het productiedomein niet voor een interne pagina.
• Externe links gebruiken een volledige https://-URL. Het schema maakt deel uit van de bestemming en mag niet worden afgeleid door een renderer.
• Afbeeldingsbronbestanden bevinden zich onder cdn-assets/seo-playbook/ en hun openbare paden beginnen met /cdn-assets/seo-playbook/. Voeg de goedgekeurde groep en bestandsnaam pas toe nadat het asset bestaat.
• Alternatieve tekst beschrijft de informatie die door een afbeelding wordt overgebracht, niet de bestandsnaam of decoratieve verschijning. Een decoratieve afbeelding gebruikt een leeg alternatief, maar de relevante elementpagina moet decoratie expliciet toestaan.
• Een inline call-to-action gebruikt :button[Zichtbaar label]{href="/doel/"}. De tekst tussen haakjes is het toegankelijke label en href volgt dezelfde interne of externe padregels. Gebruik een knop alleen voor een echte volgende actie, niet om een gewone verwijzingslink prominenter te maken.

Een afbeelding is content, geen oplossing voor niet-ondersteunde lay-out. Als de afbeelding essentiële labels, cijfers of instructies bevat, herhaal die informatie dan in toegankelijke tekst of gebruik een gestructureerd element dat het blootstelt. Screenshot-capture-verzoeken blijven HTML-commentaar totdat het genoemde asset bestaat; het zijn geen gepubliceerde afbeeldingsverwijzingen en moeten screenshotsPending = true in de frontmatter zetten.

Frontmatter en body-elementen hebben verschillende taken

Frontmatter beschrijft het document als document. Body-richtlijnen beschrijven betekenisvolle blokken binnen de leeservaring. Door deze lagen gescheiden te houden, kunnen overzichtspagina’s, schema’s, routering en publicatietools metagegevens lezen zonder zichtbare proza te parseren.

Metadata-elementen leven daarom in de frontmatter: paginatitel, beschrijving, trefwoorden, publicatie- en updatedatums, canonieke- of aliasinformatie, eigenaarschap, taxonomie, playbook-koppelingen en eventuele schema-georiënteerde verzamelingen die het paginacontract daar plaatst, zoals FAQ-items op academiepagina’s. Deze velden worden nooit als :::-richtlijnen geschreven. Een zichtbaar blok dat sommige metadata herhaalt, verplaatst het gezaghebbende veld niet uit de frontmatter; het krijgt alleen een eigen body-element wanneer het een apart lezersgericht doel heeft.

Content-elementen leven in de body: definities, waarschuwingen, tips, overzichten, conclusies, checklists, vergelijkingen, bewijsblokken, voorbeelden, stappen en calls-to-action. Het zijn richtlijnen omdat hun locatie in het verhaal ertoe doet. Het verplaatsen van een waarschuwing naar de frontmatter zou deze loskoppelen van de passage waarop ze betrekking heeft; het verbergen van metadata in een body-richtlijn zou documentbrede systemen niet in staat stellen deze betrouwbaar te vinden.

Metadata is standaard vereist

Metadata stuurt routes, voorvertoningen, vindbaarheid, koppelingen en gestructureerde uitvoer voordat iemand de body leest. Een weggelaten veld kan daarom gebruikers breken die het artikel nooit renderen. Om die reden is elk metadata-element vereist, tenzij de elementpagina expliciet zegt dat het optioneel is.

Vereist betekent ingevuld met een geldige waarde, niet slechts aanwezig als lege string of lege verzameling. Leid optioneelheid niet af uit het ontbreken ervan op een andere pagina en voeg geen placeholderwaarden toe om validatie te bevredigen. Als een vereiste waarde nog niet bekend is, is de pagina niet klaar om te publiceren. Body-elementen volgen de vereistenregels van het relevante berichttype en elementpagina’s in plaats van deze metadata-standaard.

Schrijf eerst, pas elementen daarna toe

Elementselectie is een classificatietaak, terwijl schrijven een redeneertaak is. Door beide zin voor zin te proberen uit te voeren, optimaliseert de schrijver voortijdig voor componentgrenzen. Het gebruikelijke resultaat is zwakkere overgangen, ondiepe uitleg op maat van een kader, herhalende koppen gemaakt om aan opmaak te voldoen en richtlijnen gekozen omdat ze handig zijn in plaats van omdat hun doel overeenkomt.

Productie gebeurt daarom in twee afzonderlijke doorgangen:

1. Schrijf het hele artikel als platte tekst. Maak de argumentatie, voorbeelden, kanttekeningen, overgangen en conclusie af. In dit stadium mogen koppen de logica van het concept beschrijven, maar ze bepalen niet het uiteindelijke elementtype.
2. Pas elementen toe in een aparte doorgang van boven naar beneden. Bepaal voor elke kop en elk blok het doel, controleer de bibliotheek, omring overeenkomende secties, voeg gedeclareerde attributen toe en bevestig body-toewijzing en nesting.

De scheiding verbetert beide uitkomsten. De proza ontwikkelt zich volgens de vragen van de lezer in plaats van de kaderafmetingen van het huidige thema, terwijl de opmaakdoorgang vergelijkbare blokken consistent over het hele document kan vergelijken. Het maakt ook omissies zichtbaar: een schrijver kan zien dat het artikel een waarschuwing of definitie bevat voordat hij beslist hoe deze te coderen.

Lees na de structurele doorgang de pagina één keer zonder naar de richtlijnnamen te kijken. Elementen moeten een coherent artikel ondersteunen, niet veranderen in een stapel losgekoppelde widgets. Inspecteer daarna één keer de bron zonder de proza te beoordelen, en controleer fences, attributen, geneste items, paden en vereiste metadata.

Het drie-notatiecontract

Een element wordt eenmalig gedefinieerd door zijn doel, canonieke velden, toegestane waarden, body-toewijzing, toegankelijkheidsgedrag, gestructureerde-uitvoergedrag en versie. Die definitie is de bron van waarheid. De drie platformnotaties zijn adapters ervoor, niet drie onafhankelijke componentontwerpen.

De representatieve vormen leggen de toewijzing uit; de individuele elementpagina publiceert de exacte ondersteunde naam en velden. Auteurs werken in de notatie die vereist is door hun publicatieworkflow, maar ze hernoemen geen velden, voegen geen platform-only betekenissen toe of imiteren handmatig de HTML van een andere renderer.

De elementeigenaar onderhoudt de canonieke definitie en beslist of een voorgestelde wijziging compatibel of versiebeheerd is. Hugo- en WordPress-beheerders zijn eigenaar van hun adapters en testen ze tegen gedeelde fixtures: dezelfde titel, content, attributen, items, links en toegankelijkheidsverwachtingen moeten alle drie paden overleven. Redactionele eigenaren verifiëren doel en voorbeelden. Geen platformbeheerder mag de redactionele betekenis lokaal herdefiniëren; als een platform het contract niet kan uitdrukken, is dat een adapterdefect of een voorgestelde contractwijziging.

Dit model laat presentatie verschillen waar platforms het vereisen, terwijl de semantiek stabiel blijft. Hugo kan server-side HTML renderen en WordPress kan een blokcommentaar opslaan, maar een waarschuwing blijft een waarschuwing, een checklistitem blijft een item en dezelfde vereiste velden blijven stroomafwaarts beschikbaar.

Versiebeheer van gepubliceerde elementen

Gepubliceerde content is beoordeeld tegen de elementbetekenis die bestond op het moment van publicatie. Het stilletjes wijzigen van die betekenis kan waarschuwingen, gestructureerde gegevens, toegankelijkheid of imports veranderen zonder dat een redacteur de pagina aanraakt. Versiebeheer beschermt die redactionele goedkeuring.

Gebruik het volgende wijzigingsbeleid:

• Compatibele rendererwijziging: Een visuele verfijning, prestatieverbetering of bugfix die doel, velden, geaccepteerde waarden, body-toewijzing en uitvoerbetekenis behoudt, kan binnen de huidige versie worden uitgebracht. Bestaande pagina’s ontvangen het via de renderer.
• Compatibele additieve wijziging: Een nieuw optioneel attribuut mag zich alleen bij de huidige versie voegen als de afwezigheid ervan de bestaande uitvoer behoudt en elke adapter het veilig kan negeren of ondersteunen. De definitie en platformtests veranderen samen.
• Baanbrekende wijziging: Een hernoemd of verwijderd veld, een nieuw vereist veld, gewijzigde body-toewijzing, gewijzigd doel, gewijzigde standaard met semantisch effect of incompatibele geneste-itemstructuur creëert een nieuwe majeure elementversie.
• Veroudering: De oude versie blijft renderbaar voor gepubliceerde pagina’s. De elementpagina identificeert de vervanging en het migratiepad; nieuwe pagina’s gebruiken de huidige versie.
• Migratie: Een contentmigratie is expliciet, afgebakend, voorvertoond in Markdown, Hugo en WordPress en redactioneel gevalideerd vóór publicatie. Documenteer welke pagina’s zijn gewijzigd en waarom. Laat een renderer niet raden hoe oude bron moet worden geherinterpreteerd.

Wanneer er geen versie in de bron is geschreven, gebruikt het element de basisversie zoals gedefinieerd toen dit contract werd aangenomen. Die impliciete basis moet stabiel blijven. Nieuwe majeure versies identificeren zichzelf via het versiemechanisme dat op de elementpagina is gedeclareerd; ze hergebruiken de onversioneerde syntaxis niet.

Terugdraaien is ook belangrijk. Houd de vorige renderer en bronweergave beschikbaar totdat gemigreerde pagina’s structurele, visuele, toegankelijkheids- en gestructureerde-uitvoercontroles doorstaan. Als een migratie mislukt, herstel dan de vorige versietoewijzing in plaats van het element plat te slaan tot vrije tekst, wat de semantiek zou weggooien die versiebeheer moet beschermen.

Productie-reviewchecklist

Gebruik deze eindreview na de prozadoorgang en de elementdoorgang:

• Kan het doel van elk niet-prozablok in één werkwoord worden uitgedrukt?
• Is de bibliotheek doorzocht op dat doel en nauwe synoniemen?
• Gebruikt elk overeenkomend doel zijn getypeerde element, zelfs als een H2 en alinea er hetzelfde uit zouden zien?
• Is elke resterende vrije-tekstpassage onderdeel van de doorlopende uitleg, analyse, verhaal of overgang van het artikel?
• Volgen attributen de vorm {sleutel=waarde sleutel2="waarde met spaties" .class}, met spaties gequot en alleen gedeclareerde sleutels gebruikt?
• Wordt de eerste body-kop toegewezen aan title en de rest aan content, tenzij de elementpagina een andere toewijzing declareert?
• Gebruiken herhaalbare kinderen ::item{sleutel=waarde} … ::, met bovenliggende en itemattributen op het juiste niveau geplaatst?
• Zijn interne links root-relatief met leidende en afsluitende schuine strepen, externe links absoluut en afbeeldingspaden binnen de goedgekeurde afbeeldingsroot?
• Bevinden metadata-velden zich in de frontmatter, nooit in body-richtlijnen, en zijn alle vereiste metadata-waarden volledig?
• Kunnen dezelfde canonieke velden zonder verlies worden toegewezen aan Markdown, Hugo en WordPress?
• Behoudt elke definitiewijziging oude pagina’s of introduceert het een expliciete versie en migratie?

Deze pagina is een vereiste voor elke individuele elementpagina. Elke elementdefinitie moet teruglinken naar deze basisregels en vervolgens alleen de doelspecifieke uitzonderingen documenteren: ondersteunde attributen, vereiste velden, overschrijvingen van body- of itemtoewijzing, toegestane nesting, exacte platformnamen en versiegeschiedenis. Als een elementpagina stil is, zijn de standaardwaarden op deze pagina van toepassing.