Pravidla pro psaní obsahových prvků: Kdy použít který blok

Každá stránka v SEO playbooku závisí na jednom rozlišení: část obsahu má účel, zatímco její úroveň nadpisu a vizuální vzhled jsou pouze prezentace. Tato pravidla pro psaní prvků přeměňují toto rozlišení na produkční závazek. Dodržujte je před použitím jakékoli komponenty, převodem článku mezi publikačními systémy nebo změnou prvku, který se již vyskytuje na publikovaných stránkách.

Rychlý přehled

• Zkontrolujte knihovnu prvků podle účelu před názvem. Pokud účel prvku odpovídá práci, kterou sekce vykonává, je tento prvek povinný.
• Používejte prostý Markdown pouze poté, co potvrdíte, že žádný typovaný prvek nepředstavuje účel dané pasáže. Volný text je záložní možnost, nikoli výchozí.
• Napište celý článek nejprve jako prostý text. Prvky aplikujte v samostatném strukturním průchodu shora dolů, aby kompozice a značkování nesoutěžily o pozornost.
• Považujte směrnici Markdown za kanonický autorský obsah. Renderovací moduly Hugo a WordPress mapují stejná pole a tělo do nativního výstupu platformy.
• Udržujte stávající publikované stránky na významu, podle kterého byly recenzovány. Změna definice, která narušuje kompatibilitu, vytvoří novou verzi a explicitní migraci; nikdy tiše nepřevykládá starý obsah.

Hlavní pravidlo priority

Knihovna musí být kontrolována podle toho, co pasáž dělá, ne podle toho, jak ji autor náhodou pojmenoval. Názvy se liší: jeden autor může nadepsat sekci „Co je to churn?“, jiný „Vysvětlení churnu“ a třetí „Pracovní definice“. Jejich účel je totožný, takže všechny tři mapují na stejný definiční prvek.

Tato priorita existuje, protože volný text a typovaný prvek mohou na obrazovce vypadat stejně, ale chovat se zcela odlišně v navazujících systémech. Stylizovaný nadpis následovaný odstavcem může v prohlížeči připomínat definiční box, ale nenese žádnou identitu komponenty. Nemůže spolehlivě produkovat strukturovaný výstup definice, vystavit svá pole jinému renderovacímu modulu, zachovat sémantiku během migrace ani být nalezen kontrolou kvality, která zjišťuje, zda stránka obsahuje definici. Typovaný prvek mapuje na komponentu a známý tvar dat; vizuálně podobný volný text nemapuje na nic.

Pravidlo je proto přísné:

Před napsáním nebo schválením jakéhokoli nadpisu nebo obsahového bloku identifikujte jeho účel. Pokud tento účel odpovídá definici prvku, použijte prvek. Vizuální podobnost, existující H2 nebo schopnost vyjádřit stejná slova v odstavci nečiní volný text rovnocenným.

Priorita je sémantická, nikoli vizuální. Stránka může stále obsahovat běžné nadpisy uvnitř nebo kolem prvku, pokud to jeho definice umožňuje, ale nadpis nikdy nenahrazuje typ prvku.

Volný text versus typovaný prvek

Dokud není k dispozici sdílený diagram, použijte tuto rozhodovací cestu:

1. Vyjádřete úkol pasáže jedním slovesem. Příklady zahrnují definovat, varovat, shrnout, porovnat, dokázat, instruovat nebo vyzvat k akci. Tím se zabrání tomu, aby text nadpisu maskoval skutečný účel.
2. Prohledejte knihovnu podle tohoto účelu a jeho synonym. Autor hledající pouze doslovný nadpis „Co je X?“ může přehlédnout definiční prvek, jehož stránka se jmenuje „Definiční box“.
3. Použijte odpovídající prvek, pokud existuje. Neporovnávejte vzhled ani se neptejte, zda by Markdown dokázal napodobit design; rozhodujícím faktorem je registrované chování.
4. Použijte volný text, když se žádný účel neshoduje. To je správné pro spojovací vysvětlení, argumentaci, analýzu, narativní kontext a přechody, které patří do hlavního toku článku a nevyžadují specifické chování komponenty.
5. Zaznamenejte opakovanou mezeru. Pokud se stejný nespárovaný účel objevuje na více stránkách, navrhněte prvek knihovny místo vymýšlení jednorázové směrnice nebo CSS úpravy v rámci článku.

Prostý Markdown je skutečně správný, když slova tvoří souvislé uvažování článku a nepotřebují nezávislý štítek, datový kontrakt, interakci ani cestu pro opětovné použití. Například dva odstavce vysvětlující, proč doporučení vyplývá z předchozích důkazů, jsou běžnou prózou. Kompaktní sada závěrů na začátku není běžnou prózou jen proto, že ji lze napsat jako odrážky; má rozpoznaný účel přehledového prvku nebo prvku hlavních závěrů.

Běžné záměny vedoucí k nesprávnému značkování

Tyto případy jsou uvedeny výslovně, protože snadno projdou vizuální kontrolou. Chyba se projeví až tehdy, když stránku obdrží jiný renderovací modul, validátor, vyhledávací index nebo konzument strukturovaného výstupu.

Rozlišení mezi hlavními závěry a rychlým přehledem je obzvláště důležité. Závěry použijte, když jsou položky závěry, které by si měl čtenář zapamatovat, což znamená, že je lze často napsat až poté, co článek existuje. Přehled použijte, když položky orientují čtenáře ohledně rozsahu nebo posloupnosti před čtením. Vybírejte podle tohoto redakčního úkolu, i když aktuální motiv způsobí, že obě komponenty vypadají podobně.

Syntaxe směrnic a atributů

Kanonická forma Markdown používá pojmenovanou blokovou směrnici. Atributy následují za názvem směrnice ve složených závorkách:

:::nazev-prvku{klíč=hodnota klíč2="hodnota s mezerami" .třída}
Tělo obsahu
:::

Atributy slouží k přenášení malých, stabilních vlastností, které ovlivňují význam prvku nebo podporovanou prezentaci. Jejich strojová čitelnost zabraňuje autorům skrývat konfiguraci v próze. Použijte klíč=hodnota pro hodnotu bez mezer a klíč2="hodnota s mezerami", když jsou mezery přítomny. Neuzavřená hodnota atributu nesmí obsahovat mezery. Počáteční tečka přidává podporovanou třídu, jako v .compact; není to místo pro vymýšlení stylování specifického pro stránku.

Klíče atributů jsou psány malými písmeny a používají přesný pravopis definovaný na stránce prvku. Logické a výčtové hodnoty se také řídí smlouvou dané stránky. Nevytvářejte atribut jen proto, že ho renderovací modul náhodou toleruje: nedeklarovaný atribut nemá žádnou záruku napříč platformami.

Uzavírací ::: oddělovače patří k vnějšímu prvku. Udržujte je na samostatných řádcích, aby parser mohl rozlišit tělo od následujícího odstavce. Ukázky kódu, které demonstrují směrnice, musí zůstat uvnitř ohrazených bloků kódu, jako na této stránce, aby je Hugo neinterpretoval jako obsah.

Výchozí mapování těla

Většina prvků potřebuje krátký název a delší tělo. Požadovat po autorech, aby je opakovali jako atributy, by ztížilo úpravy dlouhého textu a snadno by vedlo k nesprávnému escapování, proto tělo poskytuje výchozí mapování:

:::příklad
## Konkrétní nadpis

Zbytek těla může obsahovat odstavce, seznamy, odkazy a další obsah povolený definicí prvku.
:::

Pokud stránka prvku výslovně nepřepisuje toto pravidlo, první nadpis v těle se mapuje na title a vše za tímto nadpisem se mapuje na content. Značka nadpisu vyjadřuje hierarchii zdroje pro editory; mapované pole umožňuje každé platformě vykreslit příslušnou sémantickou úroveň nadpisu v kontextu.

Pouze první nadpis těla získává toto zvláštní zacházení. Pozdější nadpisy zůstávají součástí content. Pokud tělo nemá nadpis, title chybí; to je platné pouze tehdy, když definice prvku označuje svůj název jako volitelný. Pokud prvek definuje pojmenované sloty nebo jiné mapování, má jeho vlastní stránka přednost před tímto výchozím, protože renderovací modul musí přesně vědět, kam který fragment patří.

Vnořené položky

Některé prvky obsahují opakovatelný seznam, jehož položky potřebují vlastní atributy a tělo, například kroky s identifikátory, karty s popisky nebo položky kontrolního seznamu s počátečním stavem. Srovnání těchto položek do jednoho seznamu Markdown by ztratilo jejich jednotlivá pole, proto vnořené položky používají explicitní směrnici položky:

:::rodičovský-prvek{variant=compact}
::položka{klíč=hodnota}
### Název první položky

Vysvětlení první položky.
::
::položka{klíč2="hodnota s mezerami"}
### Název druhé položky

Vysvětlení druhé položky.
::
:::

Smlouva je ::položka{klíč=hodnota} … ::: dvě dvojtečky otevírají každou položku, jednotný název je položka a dvě dvojtečky ji uzavírají. Rodičovský prvek si ponechává svůj uzavírací oddělovač se třemi dvojtečkami. Tento vizuální rozdíl je důležitý, protože činí vnoření jednoznačným bez spoléhání se na odsazení, které je snadno poškozeno kopírováním a vkládáním.

Každá položka aplikuje stejné výchozí mapování těla, pokud stránka rodičovského prvku neříká jinak: její první nadpis se stává title této položky a zbytek se stává jejím content. Atributy umístěte na položku, když popisují pouze tuto položku; umístěte je na rodiče, když ovlivňují kolekci jako celek.

Odkazy, obrázky a inline tlačítka

Přenositelný zdroj potřebuje předvídatelné cesty. Relativní URL by měla být relativní vůči kořenu webu, nikoli vůči aktuálnímu souboru Markdown, protože stejný zdroj může být vykreslen v jiné hloubce souborového systému v Hugo nebo importován do WordPressu.

• Interní odkazy na stránky používají počáteční a koncové lomítko, jako odkaz na knihovnu prvků . Nepoužívejte ../, nevynechávejte počáteční lomítko ani nehardkódujte produkční doménu pro interní stránku.
• Externí odkazy používají úplnou URL s https://. Schéma je součástí cíle a nesmí být odvozováno renderovacím modulem.
• Zdrojové soubory obrázků jsou umístěny pod cdn-assets/seo-playbook/ a jejich veřejné cesty začínají na /cdn-assets/seo-playbook/. Připojte schválenou skupinu a název souboru až poté, co daný asset existuje.
• Alternativní text popisuje informaci přenášenou obrázkem, nikoli jeho název souboru nebo dekorativní vzhled. Dekorativní obrázek používá prázdný alternativní text, ale příslušná stránka prvku musí dekoraci výslovně povolovat.
• Inline výzva k akci používá :button[Viditelný popisek]{href="/cíl/"}. Text v hranatých závorkách je přístupný popisek a href se řídí stejnými pravidly pro interní nebo externí cesty. Tlačítko používejte pouze pro skutečnou následnou akci, nikoli pro zvýraznění běžného referenčního odkazu.

Obrázek je obsah, nikoli náhrada za nepodporované rozvržení. Pokud obrázek obsahuje nezbytné popisky, čísla nebo instrukce, opakujte tyto informace v přístupném textu nebo použijte strukturovaný prvek, který je vystavuje. Požadavky na pořízení snímků obrazovky zůstávají jako HTML komentáře, dokud pojmenovaný asset neexistuje; nejedná se o publikované reference obrázků a musí nastavit screenshotsPending = true v front matter.

Front matter a tělové prvky mají různé úkoly

Front matter popisuje dokument jako dokument. Tělové směrnice popisují smysluplné bloky uvnitř čtenářského zážitku. Udržování těchto vrstev odděleně umožňuje výpisovým stránkám, schématům, směrování a publikačním nástrojům číst metadata bez parsování viditelné prózy.

Metadata prvky proto žijí ve front matter: název stránky, popis, klíčová slova, datum publikace a aktualizace, kanonická nebo aliasová informace, vlastnictví, taxonomie, playbook vazby a jakékoli schématicky orientované kolekce, které tam smlouva stránky umísťuje, jako jsou položky FAQ na akademických stránkách. Tato pole se nikdy nepíší jako ::: směrnice. Viditelný blok, který opakuje některá metadata, nepřesouvá autoritativní pole z front matter; dostává vlastní tělový prvek pouze tehdy, když má samostatný účel vůči čtenáři.

Obsahové prvky žijí v těle: definice, varování, tipy, přehledy, závěry, kontrolní seznamy, srovnání, důkazní bloky, příklady, kroky a výzvy k akci. Jsou to směrnice, protože jejich umístění v narativu je důležité. Přesunutí varování do front matter by jej odpojilo od pasáže, kterou kvalifikuje; skrytí metadat v tělové směrnici by znemožnilo systémům na úrovni dokumentu je spolehlivě najít.

Metadata jsou standardně povinná

Metadata řídí cesty, náhledy, objevování, vazby a strukturovaný výstup dříve, než kdokoli čte tělo. Vynechané pole tedy může narušit konzumenty, které článek nikdy nevykreslí. Z tohoto důvodu je každý prvek metadat povinný, pokud jeho stránka výslovně neuvádí, že je volitelný.

Povinný znamená vyplněný platnou hodnotou, nikoli pouze přítomný jako prázdný řetězec nebo prázdná kolekce. Nevyvozujte volitelnost z vynechání na jiné stránce a nepřidávejte zástupné hodnoty pro splnění validace. Pokud povinná hodnota ještě není známa, stránka není připravena k publikaci. Tělové prvky se řídí pravidly požadavků příslušného typu příspěvku a stránek prvků, nikoli tímto výchozím nastavením metadat.

Nejprve pište, prvky aplikujte až poté

Výběr prvku je klasifikační úkol, zatímco psaní konceptu je uvažovací úkol. Snažit se provádět obojí větu po větě vede autora k předčasné optimalizaci na hranice komponent. Obvyklým výsledkem jsou slabší přechody, mělká vysvětlení přizpůsobená velikosti boxu, opakující se nadpisy vytvořené pro uspokojení značkování a směrnice zvolené spíše pro pohodlí než pro soulad účelu.

Produkce proto probíhá ve dvou odlišných průchodech:

1. Napište celý článek jako prostý text. Dokončete argumentaci, příklady, upřesnění, přechody a závěr. V této fázi mohou nadpisy popisovat logiku konceptu, ale neurčují konečný typ prvku.
2. Aplikujte prvky v samostatném průchodu shora dolů. U každého nadpisu a bloku uveďte jeho účel, zkontrolujte knihovnu, obalte odpovídající sekce, přidejte deklarované atributy a potvrďte mapování těla a vnoření.

Oddělení zlepšuje oba výstupy. Próza se vyvíjí podle otázek čtenáře místo podle velikostí boxů aktuálního motivu, zatímco značkovací průchod může konzistentně porovnávat podobné bloky napříč celým dokumentem. Také zviditelňuje opomenutí: autor vidí, že článek obsahuje varování nebo definici, než se rozhodne, jak ji zakódovat.

Po strukturním průchodu přečtěte stránku jednou, aniž byste se dívali na názvy směrnic. Prvky musí podporovat soudržný článek, ne ho proměnit v hromadu nesouvisejících widgetů. Poté jednou zkontrolujte zdroj, aniž byste posuzovali prózu, a ověřte oddělovače, atributy, vnořené položky, cesty a povinná metadata.

Smlouva tří notací

Prvek je definován jednou svým účelem, kanonickými poli, povolenými hodnotami, mapováním těla, chováním přístupnosti, chováním strukturovaného výstupu a verzí. Tato definice je zdrojem pravdy. Tři platformní notace jsou adaptéry na ni, nikoli tři nezávislé návrhy komponent.

Reprezentativní formy vysvětlují mapování; jednotlivá stránka prvku publikuje svůj přesný podporovaný název a pole. Autoři pracují v notaci požadované jejich publikačním pracovním postupem, ale nepřejmenovávají pole, nepřidávají významy pouze pro danou platformu ani ručně nenapodobují HTML jiného renderovacího modulu.

Vlastník prvku udržuje kanonickou definici a rozhoduje, zda je navrhovaná změna kompatibilní nebo verzovaná. Správci Hugo a WordPress vlastní své adaptéry a testují je proti sdíleným přípravkům: stejný název, obsah, atributy, položky, odkazy a očekávání přístupnosti musí přežít všechny tři cesty. Redakční vlastníci ověřují účel a příklady. Žádný správce platformy nesmí lokálně předefinovat redakční význam; pokud platforma nemůže smlouvu vyjádřit, jedná se o vadu adaptéru nebo návrh na změnu smlouvy.

Tento model umožňuje, aby se prezentace lišila tam, kde to platformy vyžadují, při zachování stabilní sémantiky. Hugo může vykreslovat HTML na straně serveru a WordPress může ukládat blokový komentář, ale varování zůstává varováním, položka kontrolního seznamu zůstává položkou a stejná povinná pole zůstávají dostupná v navazujících systémech.

Verzování publikovaných prvků

Publikovaný obsah byl recenzován podle významu prvku, který existoval v době publikace. Tichá změna tohoto významu může změnit varování, strukturovaná data, přístupnost nebo importy, aniž by se editor stránky dotkl. Verzování chrání toto redakční schválení.

Použijte následující politiku změn:

• Kompatibilní změna renderování: Vizuální vylepšení, zlepšení výkonu nebo oprava chyby, která zachovává účel, pole, přijímané hodnoty, mapování těla a význam výstupu, může být nasazena v rámci aktuální verze. Stávající stránky ji obdrží prostřednictvím renderovacího modulu.
• Kompatibilní aditivní změna: Nový volitelný atribut se může připojit k aktuální verzi pouze tehdy, když jeho absence zachovává stávající výstup a každý adaptér jej může bezpečně ignorovat nebo podporovat. Definice a platformní testy se mění společně.
• Nekompatibilní změna: Přejmenované nebo odstraněné pole, nové povinné pole, změněné mapování těla, změněný účel, změněná výchozí hodnota se sémantickým efektem nebo nekompatibilní struktura vnořených položek vytváří novou hlavní verzi prvku.
• Zastarání: Stará verze zůstává vykreslitelná pro publikované stránky. Její stránka prvku identifikuje náhradu a migrační cestu; nové stránky používají aktuální verzi.
• Migrace: Migrace obsahu je explicitní, ohraničená, náhledovaná napříč Markdown, Hugo a WordPress a redakčně validovaná před publikací. Zaznamenejte, které stránky se změnily a proč. Nenuťte renderovací modul hádat, jak by měl být starý zdroj přeinterpretován.

Pokud není ve zdroji uvedena žádná verze, prvek používá základní verzi definovanou při přijetí této smlouvy. Tento implicitní základ musí zůstat stabilní. Nové hlavní verze se identifikují pomocí verzačního mechanismu deklarovaného na stránce prvku; nepřizpůsobují si syntaxi bez verze.

Důležitý je také rollback. Udržujte předchozí renderovací modul a reprezentaci zdroje dostupné, dokud migrované stránky neprojdou strukturálními, vizuálními, přístupnostními a strukturovanými výstupními kontrolami. Pokud migrace selže, obnovte mapování předchozí verze namísto zploštění prvku do volného textu, což by zahodilo sémantiku, kterou má verzování chránit.

Produkční kontrolní seznam

Použijte tento závěrečný přezkum po průchodu prózou a průchodu prvky:

• Lze účel každého neprózového bloku vyjádřit jedním slovesem?
• Byla knihovna prohledána podle tohoto účelu a blízkých synonym?
• Používá každý odpovídající účel svůj typovaný prvek, i když by H2 a odstavec vypadaly podobně?
• Je každá zbývající pasáž volného textu součástí souvislého vysvětlení, analýzy, narativu nebo přechodu článku?
• Řídí se atributy formátem {klíč=hodnota klíč2="hodnota s mezerami" .třída}, s mezerami v uvozovkách a pouze s deklarovanými klíči?
• Mapuje se první nadpis těla na title a zbytek na content, pokud stránka prvku nedeklaruje jiné mapování?
• Používají opakovatelné podřízené prvky ::položka{klíč=hodnota} … ::, s atributy rodiče a položky umístěnými na správné úrovni?
• Jsou interní odkazy relativní ke kořenu s počátečním a koncovým lomítkem, externí odkazy absolutní a cesty obrázků uvnitř schváleného kořene obrázků?
• Jsou pole metadat ve front matter, nikoli v tělových směrnicích, a jsou všechna povinná metadata vyplněna?
• Lze stejná kanonická pole mapovat beze ztrát do Markdown, Hugo a WordPress?
• Zachovává jakákoli změna definice staré stránky nebo zavádí explicitní verzi a migraci?

Tato stránka je předpokladem pro každou jednotlivou stránku prvku. Každá definice prvku musí odkazovat zpět na tato základní pravidla a poté dokumentovat pouze své výjimky specifické pro daný účel: podporované atributy, povinná pole, přepisy mapování těla nebo položek, povolené vnoření, přesné názvy platforem a historii verzí. Pokud je stránka prvku k této problematice tichá, platí výchozí hodnoty z této stránky.