Reguli de scriere a elementelor de conținut: Când să folosiți fiecare bloc

Fiecare pagină din playbook-ul SEO se bazează pe o distincție: o bucată de conținut are un scop, în timp ce nivelul titlului și aspectul vizual sunt doar prezentare. Aceste reguli de scriere a elementelor transformă această distincție într-un contract de producție. Respectați-le înainte de a aplica orice componentă, de a converti un articol între sistemele de publicare sau de a modifica un element care apare deja pe paginile publicate.

Prezentare generală rapidă

• Verificați biblioteca de elemente după scop, nu după nume. Dacă scopul unui element se potrivește cu munca pe care o face o secțiune, acel element este obligatoriu.
• Folosiți Markdown simplu doar după ce ați confirmat că niciun element tipizat nu reprezintă scopul pasajului. Textul liber este o soluție de rezervă, nu o opțiune implicită.
• Scrieți articolul complet ca text simplu mai întâi. Aplicați elementele într-o trecere structurală separată, de sus în jos, astfel încât compoziția și marcarea să nu concureze pentru atenție.
• Tratați directiva Markdown ca conținut canonic autorat. Renderizatoarele Hugo și WordPress mapează aceleași câmpuri și corp în ieșire nativă platformei.
• Păstrați paginile publicate existente pe semnificația față de care au fost revizuite. O modificare de definiție care întrerupe compatibilitatea creează o nouă versiune și o migrare explicită; nu reinterpretă niciodată în tăcere conținutul vechi.

Regula guvernantă a precedenței

Biblioteca trebuie verificată după ce face un pasaj, nu după cum s-a întâmplat să îl numească scriitorul. Denumirile variază: un scriitor poate intitula o secțiune „Ce este churn?", altul „Churn explicat", iar un al treilea „O definiție de lucru". Scopul lor este identic, așadar toate trei se mapează la același element de definiție.

Această precedență există deoarece textul liber și un element tipizat pot arăta identic pe ecran, comportându-se complet diferit în aval. Un titlu stilizat urmat de un paragraf poate semăna cu o casetă de definiție în browser, dar nu poartă nicio identitate de componentă. Nu poate produce în mod fiabil ieșirea structurată a definiției, nu poate expune câmpurile sale unui alt renderizator, nu își poate păstra semantica în timpul migrării și nu poate fi găsit de o verificare a calității care întreabă dacă pagina conține o definiție. Elementul tipizat se mapează la o componentă și o formă cunoscută de date; textul liber similar vizual nu se mapează la nimic.

Regula este, așadar, strictă:

Înainte de a scrie sau aproba orice titlu sau bloc de conținut, identificați scopul acestuia. Dacă acel scop se potrivește cu o definiție de element, folosiți elementul. Similitudinea vizuală, un H2 existent sau capacitatea de a exprima aceleași cuvinte într-un paragraf nu fac textul liber echivalent.

Precedența este semantică, nu vizuală. O pagină poate conține în continuare titluri obișnuite în interiorul sau în jurul unui element atunci când definiția acestuia le permite, dar titlul nu înlocuiește niciodată tipul elementului.

Text liber versus element tipizat

Folosiți această cale decizională până când diagrama partajată este disponibilă:

1. Exprimați în un singur verb sarcina pasajului. Exemple includ: defini, avertiza, rezuma, compara, dovedi, instrui sau invita la acțiune. Acest lucru împiedică textul titlului să camufleze scopul subiacent.
2. Căutați în bibliotecă după acel scop și sinonimele sale. Un scriitor care caută doar titlul literal „Ce este X?" poate rata un element de definiție a cărui pagină se numește „Casetă de definiție".
3. Folosiți elementul potrivit atunci când există. Nu comparați aparențele și nu întrebați dacă Markdown ar putea imita designul; comportamentul înregistrat este factorul decisiv.
4. Folosiți text liber atunci când niciun scop nu se potrivește. Acest lucru este corect pentru explicații de legătură, argumente, analize, context narativ și tranziții care aparțin fluxului principal al articolului și nu necesită un comportament distinct de componentă.
5. Înregistrați un decalaj repetat. Dacă același scop nepotrivit apare în mai multe pagini, propuneți un element de bibliotecă în loc să inventați o directivă unică sau un tratament CSS într-un articol.

Markdown simplu este corect atunci când cuvintele formează raționamentul continuu al articolului și nu au nevoie de o etichetă independentă, un contract de date, o interacțiune sau o cale de reutilizare. De exemplu, două paragrafe care explică de ce o recomandare decurge din dovezile precedente sunt proză normală. Un set compact de concluzii în partea de sus nu este proză normală doar pentru că poate fi scris sub formă de marcatori; are scopul recunoscut al unui element de prezentare generală sau de concluzii principale.

Confuzii frecvente care cauzează marcare incorectă

Aceste cazuri sunt listate explicit deoarece trec ușor de o revizuire vizuală. Greșeala devine vizibilă doar atunci când un alt renderizator, validator, index de căutare sau consumator de ieșire structurată primește pagina.

Distincția dintre concluzii principale și o prezentare generală rapidă este deosebit de importantă. Folosiți concluzii principale atunci când elementele sunt concluzii pe care cititorul ar trebui să le rețină, ceea ce înseamnă că adesea pot fi scrise doar după ce articolul există. Folosiți o prezentare generală atunci când elementele orientează cititorul cu privire la domeniu sau succesiune înainte de lectură. Alegeți în funcție de acea sarcină editorială, chiar dacă tema curentă face ca ambele componente să arate la fel.

Sintaxa directivelor și atributelor

Forma canonică Markdown folosește o directivă de bloc denumită. Atributele urmează numele directivei între acolade:

:::nume-element{cheie=valoare cheie2="valoare cu spații" .clasă}
Conținutul corpului
:::

Atributele există pentru a transporta proprietăți mici și stabile care afectează semnificația elementului sau prezentarea acceptată. Păstrarea lor lizibilă pentru mașină împiedică scriitorii să ascundă configurația în proză. Folosiți cheie=valoare pentru o valoare fără spații și cheie2="valoare cu spații" când sunt prezente spații. O valoare de atribut neîntre ghilimele nu poate conține spații. Un punct de început adaugă o clasă acceptată, ca în .compact; nu este un loc pentru a inventa stilizări specifice paginii.

Cheile de atribute sunt cu litere mici și folosesc ortografia exactă definită pe pagina elementului. Valorile booleene și enumerate urmează, de asemenea, contractul acelei pagini. Nu creați un atribut doar pentru că un renderizator se întâmplă să îl tolereze: un atribut nedeclarat nu are nicio garanție cross-platformă.

Delimitatoarele de închidere ::: aparțin elementului exterior. Păstrați-le pe propriile lor linii, astfel încât un parser să poată distinge corpul de următorul paragraf. Exemplele de cod care demonstrează directive trebuie să rămână în interiorul blocurilor de cod delimitate, așa cum fac pe această pagină, pentru ca Hugo să nu le interpreteze ca conținut.

Maparea implicită a corpului

Majoritatea elementelor au nevoie de un titlu scurt și un corp mai lung. A solicita autorilor să repete acestea ca atribute ar face textul lung dificil de editat și ușor de escapat incorect, așadar corpul oferă maparea implicită:

:::exemplu
## Un titlu concret

Restul corpului poate conține paragrafe, liste, linkuri și alt conținut permis de definiția elementului.
:::

Cu excepția cazului în care o pagină de element suprascrie explicit regula, primul titlu din corp se mapează la title, iar tot ce urmează după acel titlu se mapează la content. Marcatorul titlului exprimă ierarhia sursei pentru editori; câmpul mapat permite fiecărei platforme să redea nivelul de titlu semantic adecvat în context.

Doar primul titlu al corpului primește acest tratament special. Titlurile ulterioare rămân parte din content. Dacă corpul nu are titlu, title este absent; acest lucru este valid doar atunci când definiția elementului marchează titlul ca opțional. Dacă un element definește fante denumite sau o mapare diferită, propria sa pagină are prioritate față de această implicită, deoarece renderizatorul trebuie să știe exact unde aparține fiecare fragment.

Elemente imbricate

Unele elemente conțin o listă repetabilă ale cărei intrări necesită fiecare atribute și un corp, cum ar fi pași cu identificatori, carduri cu etichete sau elemente de listă de verificare cu o stare inițială. Aplatizarea acestor intrări într-o singură listă Markdown ar pierde câmpurile lor individuale, așadar elementele imbricate folosesc o directivă explicită de element:

:::element-părinte{variant=compact}
::element{cheie=valoare}
### Titlul primului element

Explicația primului element.
::
::element{cheie2="valoare cu spații"}
### Titlul celui de-al doilea element

Explicația celui de-al doilea element.
::
:::

Contractul este ::element{cheie=valoare} … ::: două puncte duble deschid fiecare element, numele la singular este element, iar două puncte duble îl închid. Părintele păstrează delimitatorul său de închidere cu trei puncte. Această diferență vizuală contează deoarece face imbricarea neambiguă fără a se baza pe indentare, care este ușor deteriorată prin copiere și lipire.

Fiecare element aplică aceeași mapare implicită a corpului, cu excepția cazului în care pagina elementului părinte spune altfel: primul său titlu devine title al acelui element, iar restul devine content-ul său. Puneți atribute pe element atunci când descriu doar acel element; puneți-le pe părinte atunci când afectează colecția în ansamblu.

Linkuri, imagini și butoane inline

Sursa portabilă are nevoie de căi predicibile. Un URL relativ ar trebui să fie relativ la rădăcina site-ului, nu la fișierul Markdown curent, deoarece aceeași sursă poate fi redată la o adâncime diferită a sistemului de fișiere în Hugo sau importată în WordPress.

• Linkurile către pagini interne folosesc o bară oblică la început și la sfârșit, așa cum face linkul către biblioteca de elemente . Nu folosiți ../, nu omiteți bara oblică de început și nu codificați direct domeniul de producție pentru o pagină internă.
• Linkurile externe folosesc un URL complet https://. Schema face parte din destinație și nu trebuie inferată de un renderizator.
• Fișierele sursă de imagini se află sub cdn-assets/seo-playbook/, iar căile lor publice încep cu /cdn-assets/seo-playbook/. Adăugați grupul și numele fișierului aprobate doar după ce activul există.
• Textul alternativ descrie informația transmisă de o imagine, nu numele fișierului sau aspectul decorativ al acesteia. O imagine decorativă folosește un text alternativ gol, dar pagina elementului relevant trebuie să permită în mod explicit decorarea.
• Un îndemn la acțiune inline folosește :button[Etichetă vizibilă]{href="/țintă/"}. Textul dintre paranteze drepte este eticheta accesibilă, iar href urmează aceleași reguli de cale internă sau externă. Folosiți un buton doar pentru o acțiune următoare reală, nu pentru a face un link de referință obișnuit mai proeminent.

O imagine este conținut, nu o soluție pentru un aspect nesuportat. Dacă imaginea conține etichete, numere sau instrucțiuni esențiale, repetați acea informație în text accesibil sau folosiți un element structurat care o expune. Solicitările de capturi de ecran rămân comentarii HTML până când activul numit există; nu sunt referințe publicate la imagini și trebuie să seteze screenshotsPending = true în front matter.

Frontmatter-ul și elementele corpului au sarcini diferite

Frontmatter-ul descrie documentul ca document. Directivele corpului descriu blocuri semnificative în cadrul experienței de lectură. Păstrarea acestor straturi separate permite paginilor de listare, schemelor, rutării și instrumentelor de publicare să citească metadatele fără a analiza proza vizibilă.

Elementele de metadate trăiesc, așadar, în frontmatter: titlul paginii, descrierea, cuvintele cheie, datele de publicare și actualizare, informațiile canonice sau de alias, proprietatea, taxonomia, conexiunile playbook-ului și orice colecții orientate pe scheme pe care contractul paginii le plasează acolo, cum ar fi intrările FAQ pe paginile de academie. Aceste câmpuri nu sunt niciodată scrise ca directive :::. Un bloc vizibil care repetă unele metadate nu mută câmpul autoritar din frontmatter; primește propriul element de corp doar atunci când are un scop separat orientat către cititor.

Elementele de conținut trăiesc în corp: definiții, avertismente, sfaturi, prezentări generale, concluzii principale, liste de verificare, comparații, blocuri de dovezi, exemple, pași și îndemnuri la acțiune. Sunt directive deoarece locația lor în narațiune contează. Mutarea unui avertisment în frontmatter l-ar deconecta de pasajul pe care îl califică; ascunderea metadatelor într-o directivă a corpului ar face ca sistemele la nivel de document să nu le poată găsi în mod fiabil.

Metadatele sunt obligatorii în mod implicit

Metadatele conduc rutele, previzualizările, descoperirea, conexiunile și ieșirea structurată înainte ca cineva să citească corpul. Un câmp omis poate, așadar, să distrugă consumatorii care nu redea niciodată articolul. Din acest motiv, fiecare element de metadate este obligatoriu, cu excepția cazului în care pagina sa de element spune explicit că este opțional.

Obligatoriu înseamnă populat cu o valoare validă, nu doar prezent ca șir gol sau colecție goală. Nu inferați opționalitatea din omisiunea altei pagini și nu adăugați valori de substituție pentru a satisface validarea. Dacă o valoare obligatorie nu este încă cunoscută, pagina nu este pregătită pentru publicare. Elementele corpului urmează regulile de cerințe ale tipului de postare relevant și ale paginilor de element, mai degrabă decât această valoare implicită a metadatelor.

Scrieți mai întâi, aplicați elementele în al doilea rând

Selectarea elementelor este o sarcină de clasificare, în timp ce redactarea este o sarcină de raționament. Încercarea de a le executa pe amândouă propoziție cu propoziție face ca scriitorul să optimizeze prematur pentru limitele componentelor. Rezultatul obișnuit este tranziții mai slabe, explicații superficiale dimensionate pentru o casetă, titluri repetitive create pentru a satisface marcarea și directive alese pentru că sunt convenabile, nu pentru că scopul lor se potrivește.

Producția are loc, așadar, în două treceri distincte:

1. Scrieți întregul articol ca text simplu. Finalizați argumentul, exemplele, calificările, tranzițiile și concluzia. În această etapă, titlurile pot descrie logica draftului, dar nu stabilesc tipul final al elementului.
2. Aplicați elementele într-o trecere separată, de sus în jos. Pentru fiecare titlu și bloc, enunțați scopul său, verificați biblioteca, înfășurați secțiunile potrivite, adăugați atributele declarate și confirmați maparea corpului și imbricarea.

Separarea îmbunătățește ambele ieșiri. Proza se dezvoltă conform întrebărilor cititorului, în locul dimensiunilor cutiilor temei curente, în timp ce trecerea de marcare poate compara blocuri similare în mod consecvent pe întreg documentul. Face, de asemenea, omisiunile vizibile: un scriitor poate vedea că articolul conține o avertizare sau o definiție înainte de a decide cum să o codifice.

După trecerea structurală, citiți pagina o dată fără a privi numele directivelor. Elementele trebuie să susțină un articol coerent, nu să îl transforme într-un teanc de widget-uri deconectate. Apoi inspectați sursa o dată fără a judeca proza, verificând delimitatoarele, atributele, elementele imbricate, căile și metadatele obligatorii.

Contractul celor trei notații

Un element este definit o singură dată prin scopul său, câmpurile canonice, valorile permise, maparea corpului, comportamentul de accesibilitate, comportamentul de ieșire structurată și versiunea. Acea definiție este sursa de adevăr. Cele trei notații de platformă sunt adaptoare la aceasta, nu trei modele independente de componente.

Formele reprezentative explică maparea; pagina elementului individual publică numele și câmpurile exacte suportate. Autorii lucrează în notația cerută de fluxul lor de lucru de publicare, dar nu redenumesc câmpuri, nu adaugă semnificații specifice platformei și nu imită manual HTML-ul unui alt renderizator.

Proprietarul elementului menține definiția canonică și decide dacă o modificare propusă este compatibilă sau versionată. Responsabilii Hugo și WordPress dețin propriile adaptoare și le testează împotriva unor seturi de date comune: același titlu, conținut, atribute, elemente, linkuri și așteptări de accesibilitate trebuie să supraviețuiască tuturor celor trei căi. Proprietarii editoriali verifică scopul și exemplele. Niciun responsabil de platformă nu poate redefini semnificația editorială la nivel local; dacă o platformă nu poate exprima contractul, aceasta este o defecțiune a adaptorului sau o propunere de modificare a contractului.

Acest model permite ca prezentarea să difere acolo unde platformele o cer, păstrând în același timp semantica stabilă. Hugo poate reda HTML pe server, iar WordPress poate stoca un comentariu de bloc, dar o avertizare rămâne o avertizare, un element de listă de verificare rămâne un element, iar aceleași câmpuri obligatorii rămân disponibile în aval.

Versionarea elementelor publicate

Conținutul publicat a fost revizuit față de semnificația elementului care exista la momentul publicării. Schimbarea tăcută a acelei semnificații poate modifica avertismentele, datele structurate, accesibilitatea sau importurile fără ca un editor să atingă pagina. Versionarea protejează acea aprobare editorială.

Folosiți următoarea politică de modificare:

• Modificare compatibilă a renderizatorului: O rafinare vizuală, o îmbunătățire de performanță sau o remediere de eroare care păstrează scopul, câmpurile, valorile acceptate, maparea corpului și semnificația ieșirii poate fi livrată în versiunea curentă. Paginile existente o primesc prin renderizator.
• Modificare aditivă compatibilă: Un atribut opțional nou se poate alătura versiunii curente doar atunci când absența sa păstrează ieșirea existentă și fiecare adaptor poate ignora sau suporta în siguranță atributul. Definiția și testele de platformă se schimbă împreună.
• Modificare care întrerupe compatibilitatea: Un câmp redenumit sau eliminat, un câmp obligatoriu nou, o mapare schimbată a corpului, un scop schimbat, o valoare implicită schimbată cu efect semantic sau o structură de elemente imbricate incompatibilă creează o nouă versiune majoră a elementului.
• Deprecere: Versiunea veche rămâne redabilă pentru paginile publicate. Pagina sa de element identifică înlocuitorul și calea de migrare; paginile noi folosesc versiunea curentă.
• Migrare: O migrare de conținut este explicită, delimitată, previzualizată pe Markdown, Hugo și WordPress și validată editorial înainte de publicare. Înregistrați ce pagini s-au schimbat și de ce. Nu faceți un renderizator să ghicească cum ar trebui reinterpretată sursa veche.

Când nicio versiune nu este scrisă în sursă, elementul folosește versiunea de bază definită atunci când acest contract a fost adoptat. Acea bază implicită trebuie să rămână stabilă. Noile versiuni majore se identifică prin mecanismul de versiune declarat pe pagina elementului; nu reutilizează sintaxa neversionată.

Rolul invers contează, de asemenea. Păstrați renderizatorul anterior și reprezentarea sursă disponibile până când paginile migrate trec verificările structurale, vizuale, de accesibilitate și de ieșire structurată. Dacă o migrare eșuează, restaurați maparea versiunii anterioare, în loc să aplatizați elementul în text liber, ceea ce ar arunca semantica pe care versionarea intenționează să o protejeze.

Lista de verificare pentru revizuirea producției

Folosiți această revizuire finală după trecerea de proză și trecerea de elemente:

• Poate fi exprimat scopul fiecărui bloc non-proză într-un singur verb?
• A fost căutată biblioteca după acel scop și sinonimele apropiate?
• Folosește fiecare scop potrivit elementul său tipizat, chiar și atunci când un H2 și un paragraf ar arăta similar?
• Este fiecare pasaj rămas de text liber parte a explicației continue, analizei, narațiunii sau tranziției articolului?
• Urmează atributele formatul {cheie=valoare cheie2="valoare cu spații" .clasă}, cu spațiile puse între ghilimele și doar cheile declarate folosite?
• Se mapează primul titlu al corpului la title și restul la content, cu excepția cazului în care pagina elementului declară o altă mapare?
• Folosesc elementele copil repetabile formatul ::element{cheie=valoare} … ::, cu atributele părintelui și elementului plasate la nivelul corect?
• Sunt linkurile interne relative la rădăcină, cu bare oblice la început și sfârșit, linkurile externe absolute, iar căile imaginilor în interiorul rădăcinii de imagini aprobate?
• Sunt câmpurile de metadate în frontmatter, niciodată în directive ale corpului, și sunt toate valorile obligatorii de metadate complete?
• Se pot mapa aceleași câmpuri canonice fără pierderi către Markdown, Hugo și WordPress?
• Păstrează orice modificare de definiție paginile vechi sau introduce o versiune explicită și o migrare?

Această pagină este o condiție prealabilă pentru fiecare pagină individuală de element. Fiecare definiție de element trebuie să trimită înapoi la aceste reguli de bază, apoi să documenteze doar excepțiile specifice scopului său: atribute suportate, câmpuri obligatorii, suprascrieri ale mapării corpului sau elementelor, imbricare permisă, nume exacte de platformă și istoricul versiunilor. Dacă o pagină de element este tăcută, se aplică valorile implicite din această pagină.