Pravidlá pre obsahové prvky: Kedy použiť aký blok

Každá stránka v SEO playbooku závisí od jedného rozlíšenia: časť obsahu má účel, zatiaľ čo jej úroveň nadpisu a vizuálny vzhľad sú len prezentáciou. Tieto pravidlá písania prvkov premieňajú toto rozlíšenie na produkčný kontrakt. Dodržiavajte ich pred aplikovaním akéhokoľvek komponentu, konvertovaním článku medzi publikačnými systémami alebo zmenou prvku, ktorý sa už nachádza na publikovaných stránkach.

Rýchly prehľad

• Skontrolujte knižnicu prvkov podľa účelu pred názvom. Ak účel prvku zodpovedá úlohe, ktorú sekcia vykonáva, je tento prvok povinný.
• Používajte čistý Markdown len po potvrdení, že žiadny typovaný prvok nereprezentuje účel pasáže. Voľný text je záložná možnosť, nie štandard.
• Napíšte celý článok najskôr ako čistý text. Prvky aplikujte v samostatnom štrukturálnom priechode zhora nadol, aby kompozícia a značkovanie nesúťažili o pozornosť.
• Považujte Markdown direktívu za kanonický autorský obsah. Hugo a WordPress renderery mapujú rovnaké polia a telo do natívneho výstupu platformy.
• Zachovajte existujúce publikované stránky s významom, na ktorom boli posúdené. Zmena narúšajúca definíciu vytvára novú verziu a explicitnú migráciu; nikdy ticho nepreinterpretúva starý obsah.

Hlavné pravidlo priority

Knižnicu treba kontrolovať podľa toho, čo pasáž robí, nie podľa toho, ako ju autor náhodou nazval. Názvy sa líšia: jeden autor môže nadpísať sekciu „Čo je churn?“, druhý „Churn vysvetlený“ a tretí „Pracovná definícia“. Ich účel je identický, preto sa všetky tri mapujú na rovnaký definičný prvok.

Táto priorita existuje, pretože voľný text a typovaný prvok môžu na obrazovke vyzerať rovnako, no správať sa úplne odlišne v ďalšom spracovaní. Štylizovaný nadpis s odsekom môže v prehliadači pripomínať definičný box, ale nenesie identitu komponentu. Nedokáže spoľahlivo produkovať štruktúrovaný výstup definície, vystaviť svoje polia inému rendereru, zachovať svoju sémantiku počas migrácie ani byť nájdený kontrolou kvality, ktorá sa pýta, či stránka obsahuje definíciu. Typovaný prvok sa mapuje na komponent a známy dátový tvar; vizuálne podobný voľný text sa nemapuje na nič.

Pravidlo je preto striktné:

Pred napísaním alebo schválením akéhokoľvek nadpisu alebo obsahového bloku identifikujte jeho účel. Ak tento účel zodpovedá definícii prvku, použite prvok. Vizuálna podobnosť, existujúci H2 alebo schopnosť vyjadriť rovnaké slová v odseku nerobí voľný text rovnocenným.

Priorita je sémantická, nie vizuálna. Stránka môže stále obsahovať bežné nadpisy vo vnútri alebo okolo prvku, ak to jeho definícia povoľuje, ale nadpis nikdy nenahrádza typ prvku.

Voľný text verzus typovaný prvok

Použite tento rozhodovací postup, kým nebude k dispozícii zdieľaný diagram:

1. Vyjadrite úlohu pasáže jedným slovesom. Príklady zahŕňajú definovať, varovať, sumarizovať, porovnať, dokázať, inštruovať alebo vyzvať na akciu. Tým sa zabráni tomu, aby text nadpisu maskoval skutočný účel.
2. Vyhľadajte v knižnici podľa tohto účelu a jeho synoným. Autor, ktorý hľadá len doslovný nadpis „Čo je X?“, môže prehliadnuť definičný prvok, ktorého stránka sa volá „Definičný box“.
3. Použite zodpovedajúci prvok, ak existuje. Neporovnávajte vzhľad ani sa nepýtajte, či by Markdown vedel napodobniť dizajn; registrované správanie je rozhodujúcim faktorom.
4. Použite voľný text, ak sa nezhoduje žiadny účel. To je správne pre spojovacie vysvetlenie, argumentáciu, analýzu, naratívny kontext a prechody, ktoré patria do hlavného toku článku a nevyžadujú osobitné správanie komponentu.
5. Zaznamenajte opakovanú medzeru. Ak sa rovnaký nespárovaný účel objaví na viacerých stránkach, navrhnite prvok do knižnice namiesto vymýšľania jednorazovej direktívy alebo CSS úpravy v článku.

Čistý Markdown je skutočne správny, keď slová tvoria súvislé uvažovanie článku a nepotrebujú nezávislý štítok, dátový kontrakt, interakciu ani cestu opätovného použitia. Napríklad dva odseky vysvetľujúce, prečo odporúčanie vyplýva z predchádzajúcich dôkazov, sú bežná próza. Kompaktná sada záverov na začiatku nie je bežná próza len preto, že sa dá napísať ako odrážky; má rozpoznaný účel prvku prehľadu alebo kľúčových poznatkov.

Časté zámery spôsobujúce nesprávne značkovanie

Tieto prípady sú uvedené explicitne, pretože ľahko prejdú vizuálnou kontrolou. Chyba sa prejaví až vtedy, keď stránku spracúva iný renderer, validátor, vyhľadávací index alebo konzument štruktúrovaného výstupu.

Rozlíšenie medzi kľúčovými poznatkami a rýchlym prehľadom je obzvlášť dôležité. Použite poznatky, keď sú položky závery, ktoré by si mal čitateľ zapamätať, čo znamená, že ich často možno napísať až po existencii článku. Použite prehľad, keď položky orientujú čitateľa na rozsah alebo postupnosť pred čítaním. Vyberajte podľa tejto redakčnej úlohy, aj keď aktuálna téma robí oba komponenty vizuálne podobnými.

Syntax direktív a atribútov

Kanonická Markdown forma používa pomenovanú blokovú direktívu. Atribúty nasledujú za názvom direktívy v zložených zátvorkách:

:::názov-prvku{kľúč=hodnota kľúč2="hodnota s medzerami" .trieda}
Obsah tela
:::

Atribúty existujú na nosenie malých, stabilných vlastností, ktoré ovplyvňujú význam prvku alebo podporovanú prezentáciu. Ich udržiavanie v strojovo čitateľnej forme bráni autorom skrývať konfiguráciu v próze. Použite kľúč=hodnota pre hodnotu bez medzier a kľúč2="hodnota s medzerami", keď sú medzery prítomné. Neúvodzkovaná hodnota atribútu nesmie obsahovať medzery. Úvodná bodka pridáva podporovanú triedu, ako napríklad .compact; nie je to miesto na vymýšľanie špecifického štýlu stránky.

Kľúče atribútov sú malými písmenami a používajú presný pravopis definovaný na stránke prvku. Boolovské a výpočtové hodnoty tiež nasledujú kontrakt tejto stránky. Nevytvárajte atribút len preto, že ho renderer náhodou toleruje: nedeklarovaný atribút nemá žiadnu medziplatformovú záruku.

Uzatváracie ::: ohraničenie patrí k vonkajšiemu prvku. Udržujte ich na samostatných riadkoch, aby parser dokázal rozlíšiť telo od nasledujúceho odseku. Ukážky kódu, ktoré demonštrujú direktívy, musia zostať v ohraničených kódových blokoch, ako na tejto stránke, aby ich Hugo neinterpretoval ako obsah.

Predvolené mapovanie tela

Väčšina prvkov potrebuje krátky názov a dlhšie telo. Vyžadovať od autorov, aby ich opakovali ako atribúty, by sťažilo úpravy dlhého textu a uľahčilo nesprávne escapovanie, preto telo poskytuje predvolené mapovanie:

:::príklad
## Konkrétny nadpis

Zvyšok tela môže obsahovať odseky, zoznamy, odkazy a ďalší obsah povolený definíciou prvku.
:::

Pokiaľ stránka prvku explicitne neprepisuje toto pravidlo, prvý nadpis v tele sa mapuje na title a všetko za týmto nadpisom sa mapuje na content. Značka nadpisu vyjadruje hierarchiu zdroja pre editorov; mapované pole umožňuje každej platforme vykresliť príslušnú sémantickú úroveň nadpisu v kontexte.

Len prvý nadpis tela má toto špeciálne zaobchádzanie. Neskoršie nadpisy zostávajú súčasťou content. Ak telo nemá nadpis, title chýba; to je platné len vtedy, keď definícia prvku označuje jeho názov ako voliteľný. Ak prvok definuje pomenované sloty alebo iné mapovanie, jeho vlastná stránka má prednosť pred týmto predvoleným nastavením, pretože renderer musí presne vedieť, kam každý fragment patrí.

Vnorené položky

Niektoré prvky obsahujú opakovateľný zoznam, ktorého položky potrebujú atribúty a telo, napríklad kroky s identifikátormi, karty s popismi alebo položky checklistu s počiatočným stavom. Zbalenie týchto položiek do jedného Markdown zoznamu by stratilo ich jednotlivé polia, preto vnorené položky používajú explicitnú direktívu položky:

:::rodičovský-prvok{variant=compact}
::položka{kľúč=hodnota}
### Názov prvej položky

Vysvetlenie prvej položky.
::
::položka{kľúč2="hodnota s medzerami"}
### Názov druhej položky

Vysvetlenie druhej položky.
::
:::

Kontrakt je ::položka{kľúč=hodnota} … ::: dve dvojbodky otvárajú každú položku, jednotný názov je položka a dve dvojbodky ju uzatvárajú. Rodič si ponecháva svoje trojdvojbodkové uzatváracie ohraničenie. Tento vizuálny rozdiel je dôležitý, pretože robí vnorenie jednoznačným bez spoliehania sa na odsadenie, ktoré je ľahko poškoditeľné kopírovaním a vkladaním.

Každá položka používa rovnaké predvolené mapovanie tela, pokiaľ stránka rodičovského prvku nehovorí inak: jej prvý nadpis sa stáva title tejto položky a zvyšok sa stáva jej content. Umiestnite atribúty na položku, keď opisujú len túto položku; umiestnite ich na rodiča, keď ovplyvňujú kolekciu ako celok.

Odkazy, obrázky a inline tlačidlá

Prenosný zdroj potrebuje predvídateľné cesty. Relatívna URL by mala byť relatívna voči koreňu stránky, nie voči aktuálnemu Markdown súboru, pretože rovnaký zdroj môže byť vykreslený v inej hĺbke súborového systému v Hugo alebo importovaný do WordPressu.

• Interné odkazy na stránky používajú úvodné a koncové lomítko, ako odkaz na knižnicu prvkov . Nepoužívajte ../, nevynechávajte úvodné lomítko ani nehardkódujte produkčnú doménu pre internú stránku.
• Externé odkazy používajú kompletnú https:// URL. Schéma je súčasťou cieľa a nesmie byť odvodená rendererom.
• Zdrojové súbory obrázkov sa nachádzajú v adresári cdn-assets/seo-playbook/ a ich verejné cesty začínajú na /cdn-assets/seo-playbook/. Pripojte schválenú skupinu a názov súboru až po existencii assetu.
• Alternatívny text opisuje informáciu, ktorú obrázok sprostredkúva, nie jeho názov súboru alebo dekoratívny vzhľad. Dekoratívny obrázok používa prázdny alternatívny text, ale príslušná stránka prvku musí explicitne povoľovať dekoráciu.
• Inline výzva na akciu používa :button[Viditeľný popis]{href="/ciel/"}. Text v zátvorkách je prístupný popis a href sa riadi rovnakými pravidlami pre interné alebo externé cesty. Tlačidlo používajte len pre skutočnú nasledujúcu akciu, nie na zvýraznenie bežného referenčného odkazu.

Obrázok je obsah, nie náhrada za nepodporované rozloženie. Ak obrázok obsahuje dôležité popisy, čísla alebo inštrukcie, zopakujte tieto informácie v prístupnom texte alebo použite štruktúrovaný prvok, ktorý ich vystavuje. Požiadavky na zachytenie snímky obrazovky zostávajú ako HTML komentáre, kým pomenovaný asset neexistuje; nie sú to publikované referencie na obrázky a musia nastaviť screenshotsPending = true v frontmatter.

Frontmatter a telové prvky majú rôzne úlohy

Frontmatter opisuje dokument ako dokument. Telové direktívy opisujú významné bloky v rámci zážitku z čítania. Udržiavanie týchto vrstiev oddelených umožňuje stránkam zoznamov, schémam, smerovaniu a publikačným nástrojom čítať metadáta bez parsovania viditeľnej prózy.

Metadátové prvky preto žijú vo frontmatter: názov stránky, popis, kľúčové slová, dátumy publikácie a aktualizácie, kanonická alebo aliasová informácia, vlastníctvo, taxonómia, prepojenia playbooku a akékoľvek schémovo orientované kolekcie, ktoré tam umiestňuje kontrakt stránky, ako napríklad FAQ položky na akademických stránkach. Tieto polia sa nikdy nepíšu ako ::: direktívy. Viditeľný blok, ktorý opakuje niektoré metadáta, nepresúva autoritatívne pole z frontmatter; dostáva vlastný telový prvok len vtedy, keď má samostatný účel voči čitateľovi.

Obsahové prvky žijú v tele: definície, varovania, tipy, prehľady, poznatky, checklisty, porovnania, dôkazové bloky, príklady, kroky a výzvy na akciu. Sú to direktívy, pretože ich umiestnenie v naratíve je dôležité. Presunutie varovania do frontmatter by ho odpojilo od pasáže, ktorú kvalifikuje; skrytie metadát v telovej direktíve by znemožnilo ich spoľahlivé nájdenie systémom na úrovni dokumentu.

Metadáta sú štandardne povinné

Metadáta riadia cesty, náhľady, objaviteľnosť, prepojenia a štruktúrovaný výstup skôr, než niekto prečíta telo. Vynechané pole preto môže narušiť konzumentov, ktorí článok nikdy nevykreslia. Z tohto dôvodu je každý metadátový prvok povinný, pokiaľ jeho stránka explicitne neuvádza, že je voliteľný.

Povinný znamená vyplnený platnou hodnotou, nie len prítomný ako prázdny reťazec alebo prázdna kolekcia. Neodvodzujte voliteľnosť z vynechania na inej stránke a nepridávajte zástupné hodnoty na splnenie validácie. Ak povinná hodnota ešte nie je známa, stránka nie je pripravená na publikáciu. Telové prvky sa riadia pravidlami požiadaviek príslušného typu príspevku a stránok prvkov, nie týmto štandardným nastavením metadát.

Píšte najskôr, prvky aplikujte až potom

Výber prvku je klasifikačná úloha, zatiaľ čo písanie je úloha uvažovania. Pokus o vykonávanie oboch po vetách vedie autora k predčasnej optimalizácii pre hranice komponentov. Obvyklým výsledkom sú slabšie prechody, plytké vysvetlenia veľkosti krabice, opakujúce sa nadpisy vytvorené na splnenie značkovania a direktívy vybrané skôr pre pohodlnosť než preto, že ich účel zodpovedá.

Produkcia prebieha v dvoch odlišných priechodoch:

1. Napíšte celý článok ako čistý text. Dokončite argument, príklady, kvalifikácie, prechody a záver. V tejto fáze nadpisy môžu opisovať logiku návrhu, ale neurčujú konečný typ prvku.
2. Aplikujte prvky v samostatnom priechode zhora nadol. Pre každý nadpis a blok uveďte jeho účel, skontrolujte knižnicu, zabaľte zodpovedajúce sekcie, pridajte deklarované atribúty a potvrďte mapovanie tela a vnorenie.

Oddelenie zlepšuje oba výstupy. Próza sa vyvíja podľa otázok čitateľa namiesto veľkostí aktuálnych krabíc témy, zatiaľ čo značkovací priechod môže konzistentne porovnávať podobné bloky v celom dokumente. Tiež robí vynechávky viditeľnými: autor môže vidieť, že článok obsahuje varovanie alebo definíciu, skôr než sa rozhodne, ako ju zakódovať.

Po štrukturálnom priechode prečítajte stránku raz bez pozerania sa na názvy direktív. Prvky musia podporovať súdržný článok, nie ho meniť na hromadu nesúvisiacich widgetov. Potom skontrolujte zdroj raz bez posudzovania prózy, overte ohraničenia, atribúty, vnorené položky, cesty a povinné metadáta.

Kontrakt troch notácií

Prvok je definovaný raz svojím účelom, kanonickými poľami, povolenými hodnotami, mapovaním tela, správaním prístupnosti, správaním štruktúrovaného výstupu a verziou. Táto definícia je zdrojom pravdy. Tri platformové notácie sú adaptéry na ňu, nie tri nezávislé návrhy komponentov.

Reprezentatívne formy vysvetľujú mapovanie; individuálna stránka prvku publikuje svoj presný podporovaný názov a polia. Autori pracujú v notácii požadovanej ich publikačným pracovným postupom, ale nepremenúvajú polia, nepridávajú významy len pre platformu ani manuálne nenapodobňujú HTML iného renderera.

Vlastník prvku udržiava kanonickú definíciu a rozhoduje, či je navrhovaná zmena kompatibilná alebo verziovaná. Hugo a WordPress správcovia vlastnia svoje adaptéry a testujú ich proti zdieľaným prípravkom: rovnaký názov, obsah, atribúty, položky, odkazy a očakávania prístupnosti musia prežiť všetky tri cesty. Redakční vlastníci overujú účel a príklady. Žiadny správca platformy nesmie lokálne predefinovať redakčný význam; ak platforma nedokáže vyjadriť kontrakt, ide o chybu adaptéra alebo návrh zmeny kontraktu.

Tento model umožňuje, aby sa prezentácia líšila tam, kde to platformy vyžadujú, pričom sémantika zostáva stabilná. Hugo môže vykresliť serverové HTML a WordPress môže ukladať blokový komentár, ale varovanie zostáva varovaním, položka checklistu zostáva položkou a rovnaké povinné polia zostávajú dostupné v ďalšom spracovaní.

Verziovanie publikovaných prvkov

Publikovaný obsah bol posúdený voči významu prvku, ktorý existoval v čase publikácie. Tichá zmena tohto významu môže zmeniť varovania, štruktúrované dáta, prístupnosť alebo importy bez toho, aby sa redaktor dotkol stránky. Verziovanie chráni toto redakčné schválenie.

Používajte nasledujúcu politiku zmien:

• Kompatibilná zmena renderera: Vizuálne vylepšenie, zlepšenie výkonu alebo oprava chyby, ktorá zachováva účel, polia, akceptované hodnoty, mapovanie tela a význam výstupu, môže byť doručená v rámci aktuálnej verzie. Existujúce stránky ju dostanú prostredníctvom renderera.
• Kompatibilná pridaná zmena: Nový voliteľný atribút sa môže pripojiť k aktuálnej verzii len vtedy, keď jeho absencia zachováva existujúci výstup a každý adaptér ho môže bezpečne ignorovať alebo podporovať. Definícia a platformové testy sa menia spoločne.
• Narúšajúca zmena: Premenované alebo odstránené pole, nové povinné pole, zmenené mapovanie tela, zmenený účel, zmenený štandard so sémantickým efektom alebo nekompatibilná štruktúra vnorených položiek vytvára novú hlavnú verziu prvku.
• Zastaranie: Stará verzia zostáva vykresliteľná pre publikované stránky. Jej stránka prvku identifikuje náhradu a migračnú cestu; nové stránky používajú aktuálnu verziu.
• Migrácia: Migrácia obsahu je explicitná, ohraničená, náhľadovaná v Markdown, Hugo a WordPress a redakčne validovaná pred publikáciou. Zaznamenajte, ktoré stránky sa zmenili a prečo. Nenechávajte renderer hádať, ako by sa mal starý zdroj reinterpretovať.

Ak v zdroji nie je napísaná žiadna verzia, prvok používa základnú verziu definovanú pri prijatí tohto kontraktu. Tento implicitný základ musí zostať stabilný. Nové hlavné verzie sa identifikujú pomocou mechanizmu verzie deklarovaného na stránke prvku; nezneužívajú syntax bez verzie.

Dôležitý je aj rollback. Zachovajte predchádzajúci renderer a reprezentáciu zdroja, kým migrované stránky neprejdú kontrolami štruktúry, vzhľadu, prístupnosti a štruktúrovaného výstupu. Ak migrácia zlyhá, obnovte mapovanie predchádzajúcej verzie namiesto sploštenia prvku na voľný text, čo by zahodilo sémantiku, ktorú má verziovanie chrániť.

Produkčný kontrolný zoznam

Použite túto záverečnú kontrolu po priechode prózy a priechode prvkov:

• Dá sa účel každého neprozaického bloku vyjadriť jedným slovesom?
• Bola knižnica prehľadaná podľa tohto účelu a blízkych synoným?
• Používa každý zodpovedajúci účel svoj typovaný prvok, aj keď by H2 a odsek vyzerali podobne?
• Je každá zostávajúca pasáž voľného textu súčasťou súvislého vysvetlenia, analýzy, naratívu alebo prechodu článku?
• Nasledujú atribúty formát {kľúč=hodnota kľúč2="hodnota s medzerami" .trieda}, s medzerami v úvodzovkách a používajú sa len deklarované kľúče?
• Mapuje sa prvý nadpis tela na title a zvyšok na content, pokiaľ stránka prvku nedeklaruje iné mapovanie?
• Používajú opakovateľné deti ::položka{kľúč=hodnota} … ::, s atribútmi rodiča a položky umiestnenými na správnej úrovni?
• Sú interné odkazy relatívne ku koreňu s úvodným a koncovým lomítkom, externé odkazy absolútne a cesty obrázkov v rámci schváleného koreňa obrázkov?
• Sú metadátové polia vo frontmatter, nikdy nie v telových direktívach, a sú všetky povinné metadátové hodnoty vyplnené?
• Dajú sa rovnaké kanonické polia mapovať bez straty do Markdown, Hugo a WordPress?
• Zachováva každá zmena definície staré stránky alebo zavádza explicitnú verziu a migráciu?

Táto stránka je predpokladom pre každú individuálnu stránku prvku. Každá definícia prvku musí odkazovať späť na tieto základné pravidlá a potom dokumentovať len svoje výnimky špecifické pre účel: podporované atribúty, povinné polia, prepísania mapovania tela alebo položiek, povolené vnorenie, presné názvy platforiem a históriu verzií. Ak je stránka prvku tichá, platia štandardné nastavenia z tejto stránky.