Obsahový Frontmatter: Polia a SEO Metadáta

Frontmatter je prvok stránky, ktorý čitatelia nikdy nevidia ako jeden blok a na ktorom závisí každý publikačný systém. Dáva dokumentu identitu, kontrakt na vykreslenie, ukážku vyhľadávania, záznam o vlastníctve, dátumy a vstupy pre schému. Poškodený frontmatter môže vybrať nesprávnu šablónu, vytvoriť kanonické konflikty, stratiť autora alebo generovať značkovanie, ktoré je v rozpore so stránkou.

Živý exemplár je záznam na úrovni dokumentu, zobrazený ako kód, pretože frontmatter sa nesmie stať dekoratívnym blokom v tele.

+++
entity = "guide-how-to"
id = "reset-api-key"
title = "How to Reset an API Key"
seoTitle = "How to Reset an API Key Safely"
description = "Reset an API key safely, replace it in every dependent service, verify the new credential, and revoke the exposed key without avoidable downtime."
url = "/academy/reset-an-api-key/"
image = "/images/academy/reset-api-key.png"
imageAlt = "API key settings with the Rotate key action highlighted"
date = "2026-08-27 10:00:00"
updated = "2026-09-03 14:30:00"
author = "maya-chen"
reviewedBy = "alex-rivera"
keywords = [ "reset API key", "rotate API key", "revoke API key" ]
taxonomy = [ "security", "account-administration" ]
canonical = "https://amicited.com/academy/reset-an-api-key/"

[[faq]]
question = "Does rotating an API key revoke the old key immediately?"
answer = "Not necessarily. Confirm the provider's rotation behavior before changing dependent services."
+++

Prečo frontmatter existuje

Pre čitateľa metadáta znižujú neistotu. Presný názov stanovuje rozsah, užitočný popis získava kliknutie, identity robia tvrdenia zodpovednými a dátumy odhaľujú, či informácie mohli zastarať. Tieto signály nemôžu kompenzovať slabý obsah, ale ich absencia núti čitateľa hádať.

Pre stroje frontmatter nahrádza inferenciu pomenovanými hodnotami. Šablóny mapujú polia na názvy prehliadača, kanonické odkazy, záznamy osôb, dátumy, kanály, indexy a JSON-LD bez scrapovania prózy. Toto je strojová extrahovateľnosť: dôležité fakty majú konzistentné umiestnenie a typ.

Postupujte podľa pravidiel písania prvkov: metadáta patria na úroveň dokumentu; prvky určené čitateľom patria do tela. Tiráž sa môže vykresliť z frontmatter, ale jej autoritatívny identifikátor zostáva tam.

Kedy ho používať — a kedy nie

Každá indexovateľná stránka potrebuje jeden frontmatter záznam pre identitu, vykreslenie a smerovanie. Koncepty ho potrebujú, keď vstupujú do produkcie, aby validácia mohla zlyhať včas.

Neschovávajte faktické informácie článku do frontmatter. Obmedzenia produktu, bezpečnostné varovania, affiliate disclosure, metódy a zdroje musia zostať viditeľné tam, kde ich čitatelia môžu vyhodnotiť. Štruktúrovaná hodnota nikdy nenahrádza zverejnenie.

Najväčšie škody spôsobujú takmer správne prípady:

• Nezávisle sa meniace navigačné štítky, kampane a sociálne popisky sú nastavenia kanálov; nepreťažujte title.
• Organizačné fakty zdieľané na celej stránke patria do organizačného záznamu stránky, nie sú skopírované do každej stránky, kde sa rozídu.
• Sekcia otázok a odpovedí patrí do [[faq]] len vtedy, keď sa rovnaký obsah vykresľuje viditeľne. Skryté FAQ len pre schému je neplatné.
• Štítok témy patrí do taxonomy; nesmie nahradiť entity, ktorá identifikuje typ príspevku dokumentu.
• Presmerovanie patrí do konfigurácie smerovania alebo schváleného poľa aliases. canonical identifikuje preferovanú verziu; nepresmerúva návštevníkov.

Kam ho umiestniť

Frontmatter začína na prvom byte znakmi +++ a končí na zodpovedajúcom ukončení pred telom. Nesmie mu predchádzať žiaden nadpis, komentár, poznámka, shortcode ani blok metadát. Polia a polia TOML patria do tohto jedného záznamu.

Telo začína za ukončovacím +++. Frontmatter nemôže byť medzi H1 a úvodom, vedľa screenshotu, vo vnútri komponentu ani na konci. Byte order mark alebo zblúdilý komentár môžu zabrániť rozpoznaniu. Duplicitné kľúče, YAML ohraničenia a druhé bloky sú neplatné.

Anatómia

Vykreslená legenda zostáva na stránke, aby zostala čitateľná a preložiteľná nezávisle od obrázku:

1. Hranica: otváracie a zatváracie +++ ohraničenia definujú jedinú oblasť metadát.
2. Identita: entity, id, type a url hovoria systémom, čo dokument je a kde sa nachádza.
3. Objavovanie: title, seoTitle, description, image, imageAlt a keywords podporujú ukážky a vyhľadávanie.
4. Pôvod: date, updated, author a reviewedBy uvádzajú, kto je zodpovedný a kedy bola práca platne zmenená.
5. Klasifikácia: taxonomy pripája stránku k riadeným kolekciám tém bez predefinovania jej identity.
6. Kontrola duplicít: canonical pomenúva preferovanú verejnú URL, keď sú ekvivalentné verzie dosiahnuteľné inde.
7. Štruktúrované kolekcie: každý [[faq]] vytvára jeden typovaný záznam otázky a odpovede pre viditeľné vykreslenie a schému.

Príklady dizajnu

Frontmatter má varianty dátových kontraktov, nie vizuálne štýly. Screenshoty párujú zdrojové záznamy s ich výslednou ukážkou alebo tirážou.

Parametre

Toto sú redakčné limity, aj keď parser akceptuje viac. „Podmienečný“ znamená povinný, keď je uvedená podmienka splnená.

Referencia podľa polí

Táto referencia definuje publikačný kontrakt pre každé pole. „Povinný“ znamená, že validácia by mala zastaviť publikáciu, keď pole alebo jeho platné odvodenie chýba. „Podmienečný“ znamená, že požiadavka je aktivovaná uvedenou skutočnosťou, napríklad že sa obrázok vykresľuje alebo prebehla nezávislá recenzia. Predvolená hodnota je bezpečná len vtedy, keď produkuje rovnaký význam, aký by redaktor zvolil zámerne.

Identita a smerovanie

title, h1 a seoTitle

• Účel — title dáva dokumentu jeho trvalé redakčné meno. h1 riadi hlavný nadpis na stránke, keď kontext rozloženia vyžaduje iné znenie. seoTitle riadi názov prehliadača/vyhľadávania, keď predvolený názov potrebuje stručný kvalifikátor alebo značku. Ich oddelenie zabraňuje tomu, aby navigačný štítok, nadpis stránky a ukážka vyhľadávania boli nútene v jednej neohrabanej reťazci.
• Typ a formát — Každý je plain-text string. title je zdrojová hodnota; chýbajúce prepísania musia padať späť na ňu. HTML, Markdown, emoji dekorácie a manuálne značky skrátenia nie sú platné hodnoty.
• Povinný? — title je povinný na každej verejnej stránke. h1 a seoTitle sú voliteľné a mali by byť vynechané, keď title funguje vo všetkých troch kontextoch.
• Limity — Používajte 30–70 znakov pre title, 20–80 pre h1 a 30–60 pre seoTitle ako redakčné pásma, nie prísľuby, že vyhľadávacie rozhranie zobrazí každý znak. Musí byť jeden vykreslený H1.
• Kto alebo čo ho spotrebúva — Šablóny stránok, názvy prehliadačov, adaptéry vyhľadávania a sociálnych sietí, navigačné karty, kanály, schema headline, osnovy prístupnosti a redakčné zoznamy.
• Pravidlá — Všetky verzie musia identifikovať rovnaký predmet, zámer a rozsah. Legitímny rozdiel rieši obmedzenie kanála: napríklad H1 môže byť „Ako otočiť API kľúč bez výpadku“, zatiaľ čo kratší SEO názov hovorí „Rotácia API kľúča: Bezpečný sprievodca krok za krokom.“ Sekcia Názov, H1 a SEO názov neskôr vysvetľuje redakčný test.
• Bežné chyby — Opakovanie kľúčového slova vo všetkých troch variantoch, vloženie značky do H1, zmena sľubu na získanie kliknutí, vloženie aktuálneho roka keď sa stránka neudržiava ročne, alebo vytvorenie troch hodnôt len preto, že existujú tri polia.

slug a url

• Účel — Slug je posledný segment cesty; url je verejná cesta relatívna k stránke, ktorá ho obsahuje. Spolu dávajú stránke stabilnú adresu pre čitateľov, crawlerov, odkazy, reporting a migrácie. Stabilita je dôležitá, pretože každý získaný odkaz a uložená záložka sa stáva závislou na tejto adrese.
• Typ a formát — Používajte malé písmená, cestu oddelenú pomlčkami, napríklad /academy/rotate-an-api-key/. Toto úložisko zaznamenáva kompletnú cestu v url; CMS, ktoré má samostatné pole slug, musí odvodiť rovnaký finálny segment.
• Povinný? — Jedinečná cesta je povinná pre každú verejnú stránku. Môže byť generovaná len tam, kde sekcia má schválené deterministické pravidlo a kontroly kolízií; stránky playbooku používajú svoje registrované hodnoty url.
• Limity — Uprednostnite krátky, čitateľný slug, ktorý zachováva rozlišujúci predmet, zvyčajne tri až osem užitočných slov. Odstráňte interpunkciu a prázdne modifikátory. Odstráňte stop slová ako „the“ alebo „a“ len vtedy, keď výsledok zostáva prirodzený a jednoznačný; neexistuje arbitrárny limit znakov, ktorý by ospravedlňoval poškodenie významu.
• Kto alebo čo ho spotrebúva — Smerovanie Hugo, interné odkazy, drobčeková navigácia, generovanie canonical, mapy stránok, kanály, analytika, presmerovania a externé referencie.
• Pravidlá — Považujte publikovaný slug za trvalý záväzok. Rozhodnite ho z trvalej témy, nie z kampane alebo prechodného roka. Keď sa názov zmení, ale téma a zámer nie, ponechajte starý slug. Ak sa stránka skutočne presúva, vytvorte novú cestu, ponechajte starú cestu v aliases, aktualizujte interné odkazy a otestujte cieľ presmerovania.
• Bežné chyby — Regenerovanie slugu pri každej zmene názvu, napchávanie synoným do cesty, ponechanie dátumov, ktoré robia evergreen obsah zastaraným, používanie zmiešaných písmen alebo podčiarkovníkov, vytváranie dvoch URL líšiacich sa len koncovým lomítkom a zmena cesty bez zachovania starej.

canonical

• Účel — Kanonická URL identifikuje preferovanú URL medzi ekvivalentnými alebo takmer ekvivalentnými prístupnými verziami. Konsoliduje identitu; nepresúva návštevníka ani neospravedlňuje nekontrolovanú duplicitu.
• Typ a formát — Jedna absolútna HTTPS URL vrátane zamýšľaného hostiteľa a normalizovanej cesty: https://amicited.com/academy/rotate-an-api-key/. Šablóna môže odvodiť self-referenciu z permalinku stránky, keď má stránka jeden dôveryhodný hostiteľ a politiku cesty.
• Povinný? — Každá indexovateľná stránka musí emitovať jeden canonical. Pole je samotné podmienečné, keď je správna self-referujúca hodnota odvodená automaticky; nastavte ho explicitne pre schválený cross-domain alebo výnimočný canonical.
• Limity — Presne jeden canonical cieľ. Cieľ musí vracať úspešný indexovateľný dokument, používať preferovaný protokol a hostiteľa a reprezentovať v podstate rovnaký obsah.
• Kto alebo čo ho spotrebúva — HTML <link rel="canonical">, vyhľadávače, kontroly mapy stránok a interných odkazov, reporty deduplikácie a identifikátory URL schémy.
• Pravidlá — Štandardne self-referencia. Používajte cross-domain canonical len vtedy, keď iný vydavateľ vlastní preferovanú ekvivalentnú verziu a obe strany zamýšľajú konsolidáciu. Používajte presmerovanie, nie canonical, keď bola stará URL nahradená a používatelia by mali vždy pristáť na novej. Udržujte canonical, URL mapy stránok, hreflang, interné odkazy a identitu schémy v súlade.
• Bežné chyby — Smerovanie každej stránkovanej alebo lokalizovanej stránky na generického rodiča, kanonizácia odlišného obsahu, cielenie na presmerovanie alebo chybovú stránku, miešanie HTTP a HTTPS, používanie poľa ako náhrady za alias a predpoklad, že canonical direktívy sú zaručene dodržané.

aliases

• Účel — aliases uchováva cesty, ktoré predtým identifikovali rovnakú stránku, aby presun nezmenil existujúce odkazy a záložky na slepé uličky. Zaznamenáva históriu cesty, nie vytvára alternatívne indexovateľné identity.
• Typ a formát — TOML pole ciest relatívnych k stránke, napríklad aliases = [ "/blog/old-api-key-guide/" ]. Každá hodnota obsahuje vedúce a koncové lomítko a musí byť jedinečná v rámci stránky.
• Povinný? — Voliteľný pre novú stránku; povinný vždy, keď sa publikovaná stránka presúva z cesty, ktorú stránka kontrolovala.
• Limity — Zahrňte každú známu predchádzajúcu prvou stranou kontrolovanú cestu, ktorá stále dostáva odkazy alebo návštevnosť. Nepridávajte špekulatívne varianty pravopisu alebo neobmedzený zoznam klúčových slovných URL.
• Kto alebo čo ho spotrebúva — Hugo alias output, spracovanie presmerovania pri nasadení ak je nakonfigurované, migračná QA, monitorovanie odkazov a používatelia nasledujúci staré URL. Pretože Hugo môže emitovať alias stránku namiesto HTTP presmerovania na úrovni pôvodu, správanie pri nasadení musí byť overené, nie predpokladané.
• Pravidlá — Presunutá stránka udržiava funkčnosť starej cesty. Každý alias musí viesť v jednom skoku na aktuálnu kanonickú cestu. Aktualizujte interné odkazy na novú URL, aj keď alias funguje, a ponechajte alias aj pri neskorších úpravách, pokiaľ ho nedokumentovaný systém presmerovania nenahradí.
• Bežné chyby — Vymazanie starej stránky bez aliasu, reťazenie starej cesty na strednú cestu na aktuálnu cestu, považovanie aliasov za duplicitné publikačné cesty, smerovanie niekoľkých nesúvisiacich stránok na jeden pohodlný cieľ alebo predpoklad, že lokálny Hugo output dokazuje produkčný HTTP status.

type a layout

• Účel — Tieto polia vyberajú vykresľovací kontrakt. type zaraďuje stránku do triedy obsahu so zdieľanými šablónami a správaním; layout žiada konkrétnu šablónu v rámci tejto triedy. Správny výber zabezpečuje, že stránka dostane zamýšľanú navigáciu, slot na obsah, assety a správanie schémy.
• Typ a formát — Malé registrované stringy. Táto stránka používa type = "academy". Hodnota layout je základný názov šablóny ako single, bez prípony súboru alebo cesty.
• Povinný? — type je povinný, keď umiestnenie obsahu bezpečne neimplikuje zamýšľaný typ alebo keď to mandátne vyžaduje kontrakt playbooku. layout je voliteľný a mal by byť vynechaný, keď je predvolená šablóna typu správna.
• Limity — Jedna hodnota pre každé pole, vybraná len z údržbovaných šablón stránky. Nová hodnota je inžinierska zmena, nie redakčná improvizácia.
• Kto alebo čo ho spotrebúva — Hugo lookup order, šablóny, výber parciálov, zahrnutie CSS a JavaScript, adaptéry schémy a validačné pravidlá.
• Pravidlá — Vyberte typ príspevku a vykresľovací kontrakt pred písaním. Používajte layout len pre skutočný podporovaný variant; nepoužívajte ho na kompenzáciu obsahu, ktorý patrí do iného type. Overte, že prepísanie existuje a akceptuje tvar frontmatter stránky.
• Bežné chyby — Mýlenie redakčného entity s Hugo type, pomenovanie šablónového súboru, ktorý neexistuje, kopírovanie typu vstupnej stránky na dokument akadémie, spoliehanie sa na inferenciu priečinka počas migrácie a zavádzanie jednorazových názvov layoutov, ktoré obchádzajú zdieľané vylepšenia.

Objavovanie

description

• Účel — Popis pomáha kvalifikovanému hľadajúcemu alebo príjemcovi zdieľania rozhodnúť, či táto stránka odpovedá na potrebu. Je to ukážkový text, nie komprimovaný úvod a nie miesto na dokazovanie relevantnosti opakovaním.
• Typ a formát — Jedna plain-text veta. Mala by prirodzene pomenovať primárny termín, uviesť konkrétnu hodnotu a pridať užitočný rozsah, publikum, metódu alebo výsledok.
• Povinný? — Povinný pre každú indexovateľnú stránku v tomto playbooku.
• Limity — 150–160 znakov vrátane medzier. Toto je redakčné konzistentné pásmo, nie garancia zobrazenia: vyhľadávače ho môžu skrátiť alebo prepísať úryvok z tela, keď iná pasáž lepšie zodpovedá dotazu.
• Kto alebo čo ho spotrebúva — Meta description tagy, predvolené popisy Open Graph a Twitter, karty zoznamov, kanály, CMS ukážky, kontroly kvality vyhľadávania a niekedy schema description.
• Pravidlá — Píšte pre kliknutie od správneho čitateľa. Urobte vetu dostatočne špecifickú na odlíšenie stránky od iného výsledku s podobným názvom. Sekcia Pravidlá pre popis nižšie uvádza odôvodnenie a testy odmietnutia.
• Bežné chyby — Duplikovanie názvu, vymenovanie kľúčových slov, otvorenie „Naučte sa všetko o“, uvedenie nepodloženého najlepšieho/najrýchlejšieho tvrdenia, používanie vágnej výzvy na akciu, prekročenie pásma cez neviditeľnú príponu značky alebo predpoklad, že autorský text sa musí objaviť doslovne vo výsledkoch vyhľadávania.

keywords

• Účel — V tomto úložisku keywords zaznamenáva kompaktnú množinu dotazov a terminológie používanú pre redakčnú QA, vyhľadávanie v korpuse, analýzu pokrytia a interné nástroje. Pomáha editorom rozpoznať jazyk, ktorý musí stránka používať presne; nie je to sľub zahrnúť každú frázu mechanicky.
• Typ a formát — Pole reťazcov v prirodzenom jazyku, usporiadaných od primárneho termínu cez zmysluplné varianty a úzko súvisiacu terminológiu.
• Povinný? — Povinný v rámci tohto playbooku, vrátane stránok, ktorých verejné šablóny hodnoty nevykresľujú.
• Limity — Šesť až osem odlišných položiek. Každá položka musí reprezentovať skutočnú frázu dotazu alebo nevyhnutný termín, nie variant na úrovni tokenov.
• Kto alebo čo ho spotrebúva — Redakčné validátory, inventúry obsahu, analýza vyhľadávania a príležitostí, interné vyhľadávanie a migračné nástroje. Verejné vyhľadávače nepoužívajú toto pole ako signál hodnotenia len preto, že existuje.
• Pravidlá — Udržujte množinu zameranú na rozsah jednej stránky. Zlúčte duplicity vo veľkosti písmen, interpunkcii, jednotnom/množnom čísle a triviálnom poradí slov. Používajte frázy na kontrolu pokrytia a terminológie, nikdy na diktovanie neprirodzenej hustoty.
• Bežné chyby — Považovanie poľa za zastaraný mechanizmus hodnotenia meta-keywords, pridávanie desiatok variantov, opakovanie názvu ako osem takmer duplicitných položiek, vkladanie mien konkurentov, o ktorých telo nehovorí, a dovolenie poľu nahradiť riadnu taxonómiu alebo ciele promptov.

targetPrompts

• Účel — targetPrompts zaznamenáva úplné otázky alebo požiadavky, ktoré môže osoba dať systému umelej inteligencie a pre ktoré by táto stránka mala byť užitočným zdrojom. Ciele promptov zachovávajú konverzačný kontext, ktorý krátke frázy kľúčových slov vynechávajú.
• Typ a formát — Pole kompletných reťazcov v prirodzenom jazyku, napríklad targetPrompts = [ "How do I rotate an API key without downtime?", "What should I check before revoking an old API key?" ]. Udržujte znenie tak, ako by sa používateľ pýtal, vrátane publika, obmedzení alebo požadovaného porovnania.
• Povinný? — Podmienečný pre stránky zahrnuté v sledovaní promptov alebo programe viditeľnosti AI; voliteľný, keď neexistuje žiadna sledovaná sada promptov.
• Limity — Používajte malú, zámernú sadu, normálne jeden primárny prompt a až štyri zmysluplné varianty. Prompt môže byť dlhší ako kľúčové slovo, pretože jeho kvalifikátory nesú zámer.
• Kto alebo čo ho spotrebúva — Briefy obsahu, pracovné postupy sledovania promptov, audity vyhľadávania a pokrytia, monitorovanie AI odpovedí a redakčné hodnotenie. Nie je vykreslený ako skrytý text vyhľadávania.
• Pravidlá — Oddeľujte prompty podľa skutočnej informačnej potreby, nie interpunkcie. Kľúčové slovo ako „rotácia API kľúča“ pomenúva tému; „Ako môže SaaS tím otočiť API kľúč bez prerušenia integrácií?“ pomenúva publikum, úlohu a obmedzenie. Stránka musí čestne odpovedať na každý uložený prompt.
• Bežné chyby — Kopírovanie poľa kľúčových slov do tohto poľa, vytváranie desiatok syntaktických variantov, zaznamenávanie promptov širších ako stránka, používanie promptov ako nadpisov tela bez ohľadu na tok čítania a tvrdenie pokrytia promptov, keď odpoveď závisí na informáciách, ktoré stránka neposkytuje.

Dôvera a pôvod

date a updated

• Účel — date uchováva, kedy bola stránka prvýkrát publikovaná; updated hlási poslednú podstatnú zmenu alebo dokončenú revíziu. Dve polia zachovávajú históriu a zároveň ukazujú, či sa zmenili informácie, na ktoré sa čitatelia spoliehajú.
• Typ a formát — Reťazce timestampu v konvencii stránky, YYYY-MM-DD HH:MM:SS. Udržujte jednu politiku časovej zóny naprieč korpusom, aby kanály a porovnania zostali deterministické.
• Povinný? — date je povinný pre publikované redakčné stránky. updated je voliteľný, kým nenastane kvalifikujúca sa zmena, potom povinný, ak stránka prezentuje modifikovaný dátum.
• Limity — Jedna hodnota každá. updated nemôže predchádzať date ani byť v budúcnosti. Oprava vykonaná minúty po publikácii môže byť stále zdokumentovaná, ale rutinné revízie konceptu pred publikovaním nevytvárajú dátum aktualizácie.
• Kto alebo čo ho spotrebúva — Viditeľné tiráže a pečiatky čerstvosti, kanály, mapy stránok, schema datePublished a dateModified, audity aktuálnosti, triedenie a redakčné fronty.
• Pravidlá — Resetujte updated pri faktickej oprave, zmene inštrukcie, novom alebo odstránenom dôkaze, revidovanom rozsahu, materiálne zmenenom odporúčaní alebo dokumentovanej revízii časovo citlivých tvrdení. Nikdy ho neresetujte pre interpunkciu, formátovanie, prácu na šablóne alebo úpravy len timestampu. Pozrite Dátumy, autori a recenzenti pre politické odôvodnenie.
• Bežné chyby — Prepísanie pôvodného dátumu počas obnovy, budúce datovanie stránky, aby vyzerala čerstvo, zvyšovanie dátumov bez diffu obsahu, považovanie automatického nasadenia za redakčnú aktualizáciu a nezaznamenanie toho, čo sa zmenilo v udržiavanej histórii aktualizácií.

author

• Účel — author prepája dokument so zodpovednou osobou, ktorá je zodpovedná za jeho prácu. Odkaz dáva čitateľovi a stroju cestu od stránky s tvrdením k udržiavanej identite, odbornosti a ďalšej práci.
• Typ a formát — Stabilný identifikátor autora, ktorý sa vyrieši cez register autorov stránky na URL profilu a záznam Person. Napríklad author = "maya-chen" je platný len vtedy, ak sa tento identifikátor vyrieši; zobrazovacie meno ako „Maya Chen, SEO Expertka“ nie je náhradou za entitný odkaz.
• Povinný? — Povinný pre podstatné redakčné stránky. Transakčné stránky môžu používať riadeného organizačného vlastníka len vtedy, keď šablóna a politika podporujú tento typ entity.
• Limity — Štandardne jeden zodpovedný vedúci; používajte zdokumentované pole identifikátorov len vtedy, keď schéma a šablóny tiráže podporujú skutočné spoluautorstvo.
• Kto alebo čo ho spotrebúva — Viditeľné tiráže, odkazy na profily autorov, Article schema, kanály, reporty redakčného vlastníctva, revízne pracovné postupy a grafy entít.
• Pravidlá — Vyriešte identifikátor pred publikáciou. Profil musí identifikovať rovnakú osobu zobrazenú v tiráži a musí zostať udržiavaný. Uveďte osobu zodpovednú za obsah, nie osobu, ktorá ho iba nahrala.
• Bežné chyby — Zadanie nespájaného mena, použitie „Admin“ alebo vymysleného redakčného tímu, priradenie výkonnému riaditeľovi, ktorý prácu nenapísal, dovolenie identifikátoru vyriešiť sa na žiadny profil a zmena autorstva na implikovanie odbornosti, ktorá nebola zapojená.

reviewedBy, reviewedAt a reviewScope

• Účel — Tieto polia zaznamenávajú nezávislú recenziu odlišnú od autorstva. reviewedBy identifikuje entitu recenzenta; reviewedAt uvádza, kedy bola recenzia dokončená; reviewScope hovorí, čo recenzent skontroloval, takže odznak neimplikuje schválenie nad rámec dôkazov.
• Typ a formát — reviewedBy je stabilný identifikátor vyriešiteľný na udržiavaný profil osoby. reviewedAt používa formát timestampu stránky. reviewScope je stručné vyhlásenie v plain texte ako „Kroky rotácie poverení a bezpečnostné upozornenia.“
• Povinný? — Podmienečný, keď zákon, politika rizika, citlivosť témy alebo špecifikácia typu príspevku vyžaduje nezávislú recenziu. Keď je reviewedBy prítomný, dátum a rozsah recenzie sú povinné ako údaje o recenznom zázname, aj keď ich konkrétna šablóna ukladá do prepojeného redakčného záznamu namiesto verejného frontmatter.
• Limity — Uvádzajte len skutočných recenzentov. Rozsah by mal byť dostatočne špecifický na odhalenie vylúčení bez toho, aby sa stal správou o recenzii. Recenzent musí mať relevantnú kompetenciu a nesmie jednoducho duplikovať rolu autora.
• Kto alebo čo ho spotrebúva — Komponenty recenzované-od, spojenia entít osôb, audity správy, brány publikovania s vysokým rizikom, štruktúrovaná proveniencia a protokoly aktualizácií.
• Pravidlá — Dokončite recenziu po stabilizácii obsahu, zachyťte zistenia a riešenia v redakčnej histórii a znovu recenzujte, keď neskoršie zmeny ovplyvnia recenzovaný rozsah. Nezávislý znamená, že recenzent testuje prácu, nie podporuje svoj vlastný koncept.
• Bežné chyby — Považovanie korektúry za odbornú recenziu, zobrazenie recenzenta bez dátumu alebo rozsahu, uvedenie niekoho, kto nikdy nevidel finálnu verziu, ponechanie odznaku po materiálne nerecenzovanom prepise a implikovanie právneho, lekárskeho alebo technického schválenia mimo uvedeného rozsahu.

Médiá a sociálne siete

image a imageAlt

• Účel — image vyberá reprezentatívny hero a sociálny asset; imageAlt poskytuje funkčnú textovú alternatívu, keď je tento asset vykreslený ako zmysluplný obsah stránky. Udržiavanie páru pohromade zabraňuje tomu, aby sa obrázky pre objavovanie stali chýbajúcou prístupnosťou.
• Typ a formát — image je riešiteľná cesta stránky alebo schválená absolútna URL. imageAlt je plain text popisujúci užitočnú informáciu obrázku v kontexte stránky, nie jeho názov súboru alebo cieľové kľúčové slovo.
• Povinný? — Podmienečný podľa typu príspevku a šablóny. Ak stránka vyžaduje hero alebo vyhradený sociálny obrázok, image je povinný. imageAlt je povinný vždy, keď sa ten obrázok vykresľuje informatívne; čisto dekoratívne vykreslenie musí používať prázdny alt atribút v šablóne, nie vymyslený popisný text.
• Limity — Používajte jeden reprezentatívny asset. Pre sociálnu kompatibilitu poskytnite zdroj 1200 × 630 pixelov v očakávanom pomere strán, udržujte dôležitý obsah ďalej od okrajov a udržujte imageAlt stručný — normálne 5–160 znakov. Súbor musí existovať predtým, než je referencovaný.
• Kto alebo čo ho spotrebúva — Hero komponenty, karty zoznamov, Open Graph a Twitter tagy, schema image polia, kanály, obrázkové pipeline, screen readery keď je viditeľný a QA assetov.
• Pravidlá — Vyberte obrázok, ktorý komunikuje aj po stredovom oreze a v zmenšenej veľkosti. Popíšte jeho funkciu v kontexte: „Nastavenia API kľúča so zvýraznenou akciou Rotate“ je užitočné; „API kľúč“ nie je. Nevkladajte podstatné tvrdenia len do pixelov.
• Bežné chyby — Referencovanie plánovaného assetu, ktorý neexistuje, používanie loga ako každého obrázku článku, vkladanie malého textu, ktorý je v zdieľaniach nečitateľný, písanie „obrázok“, napchávanie kľúčových slov do alt textu a predpoklad, že sociálny alt text a alt text viditeľného obrázku majú rovnaké správanie na všetkých platformách.

Open Graph a Twitter card polia

• Účel — Sociálne metadáta riadia, ako je URL zhrnutá pri zdieľaní. Konzistentný názov, popis, URL, typ a obrázok pomáhajú príjemcom rozpoznať stránku pred kliknutím a znižujú šancu, že platforma vyberie irelevantný asset.
• Typ a formát — V tomto úložisku šablóny odvodzujú og:title a twitter:title z title, popisy z description, URL z permalinku, og:type z kontextu layoutu a obrázkové tagy z image s fallbackom stránky. twitter:card je emitovaný ako summary_large_image. Toto sú generované tagy, nie duplicitné frontmatter polia štandardne.
• Povinný? — Výstupné tagy sú povinné na verejných stránkach. Samostatné prepísania sú voliteľné a mali by byť zavedené len prostredníctvom zdokumentovaného kontraktu šablóny; nepodporované ad hoc polia ako ogTitle nerobia nič.
• Limity — Jeden koherentný náhľad na stránku a jeden reprezentatívny obrázok 1200 × 630. Udržujte odvodené znenie v rámci pásiem názvu a popisu, potom otestujte skutočné správanie orezania a prekrytia na hlavných zdieľacích povrchoch.
• Kto alebo čo ho spotrebúva — Sociálne siete, messaging klienty, unfurler odkazov, rozšírenia prehliadača, kolaboračné nástroje a debuggery ukážok zdieľania.
• Pravidlá — Uprednostnite odvodenie, aby vyhľadávacie a sociálne tvrdenia zostali v súlade. Prepisujte len vtedy, keď sociálny kontext skutočne potrebuje iné rámcovanie a šablóna to podporuje. Nesprávny obrázok stojí uznanie a dôveru: príjemca môže vidieť zastarané rozhranie, iný produkt, zavádzajúce tvrdenie alebo orezanie, ktoré skrýva predmet.
• Bežné chyby — Vytváranie polí, ktoré žiadna šablóna nečíta, dovolenie globálnemu fallbacku maskovať chýbajúci povinný hero, používanie portrétu alebo malého obrázku pre širokú kartu, zmena sociálneho textu na silnejší sľub ako stránka a validácia len HTML zdroja namiesto načítanej ukážky.

Klasifikácia

taxonomy, categories a tags

• Účel — Klasifikácia prepája stránku s riadenými kolekciami tém, formátov, publík alebo produktov. Podporuje užitočné archívy a filtre len vtedy, keď každý slovník má deklarovaný význam; inak sa štítky stanú nekontrolovanou kopou synoným.
• Typ a formát — Polia registrovaných slugov v malých písmenách. Používajte taxonomy pre riadený slovník tém tohto úložiska. Používajte categories len pre malú vzájomne zrozumiteľnú redakčnú hierarchiu a tags len pre riadený prierezový slovník, keď sú tieto taxonómie nakonfigurované.
• Povinný? — Podmienečný podľa typu príspevku a dizajnu archívu. Redakčné stránky s témou normálne vyžadujú jeden alebo viac riadených termínov; pomocné stránky nemusia vyžadovať žiadne. Pole nesmie byť vyplnené len preto, že ho CMS vystavuje.
• Limity — Pre všeobecnú taxonómiu jedna až päť hodnôt na riadený slovník. Každý termín potrebuje definíciu, vlastníka a pravidlo zlúčenia. Vytvorte indexovateľný archív len vtedy, keď termín reprezentuje trvalý dopyt čitateľov a archív môže ponúknuť jedinečný úvod, koherentný inventár, interné odkazy a priebežnú údržbu.
• Kto alebo čo ho spotrebúva — Archívne stránky, drobčeková navigácia, filtre, systémy súvisiaceho obsahu, fasetová navigácia, audity obsahu a segmentácia analytiky.
• Pravidlá — Vyberte najužší registrovaný termín, ktorý presne zoskupuje stránku. Zmapujte varianty jednotného/množného čísla, skratiek a pravopisu na jednu kanonickú hodnotu. Rozhodnite, či sú archívy indexovateľné na úrovni slovníka, nie tag po tagu po náhodnom vytvorení.
• Bežné chyby — Používanie seo, SEO, search-optimization a search-engine-optimization ako samostatných hodnôt, pridávanie jednorazových tagov na opis každého podstatného mena, mýlenie obchodného typu s témou, generovanie slabých indexovateľných archívov a mazanie termínov bez migrácie ich členov.

Playbook join kľúče

• Účel — playbookPillar, playbookFamily, playbookWave, postTypes, elements, businessTypes, journeyStage a amicitedFeatures sú typované join kľúče. Umožňujú jednej zdrojovej stránke objaviť sa v generovaných knižniciach a matriciach bez toho, aby editori ručne kopírovali karty. Táto stránka je spracovaným príkladom: jej pilier identifikuje prvok, rodina zoskupuje pokyny pre metadáta a pole postTypes deklaruje špecifikácie, ktoré ho spotrebúvajú.
• Typ a formát — Jednotlivé kľúče používajú registrované slugy v malých písmenách: playbookPillar a playbookFamily sú stringy, playbookWave je integer a journeyStage je riadený string. Vzťahové kľúče — postTypes, elements, businessTypes a amicitedFeatures — sú polia registrovaných slugov z ich príslušných registrov.
• Povinný? — playbookPillar a playbookWave sú povinné na záznamoch playbooku. playbookFamily je povinný, kde má pilier riadené rodiny. Polia join a journeyStage sú podmienečné: vyplňte len tie vzťahy, ktoré kontrakt stránky skutočne podporuje.
• Limity — Jeden pilier, jedna rodina v rámci toho piliera, jedna vlna a jedna fáza cesty, pokiaľ model explicitne nepovoľuje viac fáz. Polia obsahujú jedinečné registrované kľúče, nie zobrazovacie štítky, prózu alebo URL.
• Kto alebo čo ho spotrebúva — Zoznamy centra playbooku, medzipilierové matice, filtre, karty vzťahov, reporty kompletnosti, zobrazenia podľa vĺn a interné nástroje, ktoré nachádzajú relevantné schopnosti AmICited.
• Pravidlá — Validujte každú hodnotu proti kanonickému registru. Smer záleží: stránka typu príspevku uvádza požadované elements; stránka prvku uvádza použiteľné postTypes; stránka obchodného typu uvádza užitočné typy príspevkov. Považujte štítky za prezentáciu a kľúče za trvalé dáta. Premenujte kľúč len prostredníctvom migrácie, ktorá aktualizuje každú stranu spojenia.
• Bežné chyby — Vymýšľanie takmer synoným, ukladanie názvov namiesto slugov, miešanie integerov a stringov pre vlny, pridávanie vzťahu, pretože dve stránky sa navzájom spomínajú, dovolenie vzájomným poliam si protirečiť a vytváranie ručne udržiavaného značkovania zoznamov, ktoré sa rozchádza s metadátami.

Odvodené a štrukturálne polia

schemaType

• Účel — schemaType vyberá najšpecifickejšie podporované mapovanie štruktúrovaných dát, ktoré presne opisuje viditeľnú stránku. Hovorí adaptéru schémy, ktorý kontrakt slovníka použiť; nemeni stránku na tú vec len deklaráciou.
• Typ a formát — Jeden registrovaný názov typu Schema.org ako Article, vybraný z typov, ktoré adaptér stránky podporuje. Veľkosť písmen a pravopis musia zodpovedať registru.
• Povinný? — Podmienečný. Nastavte ho tam, kde je viacero mapovaní schémy platných pre rovnaký Hugo typ alebo kde kontrakt typu príspevku vyžaduje explicitný typ. Inak nechajte šablónu odvodiť jej bezpečnú predvolenú hodnotu.
• Limity — Jeden primárny typ stránky, s vnorenými entitami vytvorenými adaptérom zo skutočného obsahu. Vybraný typ musí spĺňať všetky požadované vlastnosti a zodpovedať tomu, čo čitateľ vidí.
• Kto alebo čo ho spotrebúva — JSON-LD adaptéry, validácia rich results, QA obsahu a reporty inventára schém.
• Pravidlá — Vyberajte z funkcie stránky a viditeľných dôkazov, nie z vyhľadávacej funkcie, ktorú chce editor. Návod bez kompletného viditeľného postupu nemôže získať presnosť nastavením typu how-to. Udržujte URL schémy, dátumy, osoby a obrázky synchronizované so svojimi zdrojovými poľami.
• Bežné chyby — Výber špecifickejšieho typu bez jeho požadovaného obsahu, emitovanie niekoľkých konfliktných primárnych typov, kopírovanie hodnoty schémy z nesúvisiacej šablóny, predpoklad, že platná syntax garantuje spôsobilosť, a vkladanie tvrdení do JSON-LD, ktoré čitatelia nemôžu skontrolovať.

Čas čítania

• Účel — Čas čítania dáva čitateľovi hrubý odhad úsilia. Je odvodený z konečného vykresliteľného tela, takže odhad sa mení, keď sa mení skutočné zaťaženie čítaním.
• Typ a formát — Vypočítaný celočíselný počet minút vytvorený z politiky počtu slov obsahovej pipeline. Bloky kódu, tabuľky, popisky a vložené médiá by mali nasledovať jedno zdokumentované pravidlo počítania.
• Povinný? — Zobrazenie je voliteľné podľa šablóny. Autorské pole frontmatter nie je povolené ako zdroj pravdy.
• Limity — Zaokrúhľujte konzistentne a aplikujte rozumné minimálne zobrazenie ako jedna minúta. Presný predpoklad slov za minútu je menej dôležitý ako použitie rovnakej metódy na celej stránke a označenie výsledku ako odhad.
• Kto alebo čo ho spotrebúva — Hlavičky stránok, karty, kanály, segmentácia analytiky a čitatelia rozhodujúci sa, či začať dlhý sprievodca.
• Pravidlá — Vypočítajte po spracovaní shortcodes a vylúčených oblastí podľa politiky stránky. Prepočítajte pri každom buildu. Ak video alebo interaktívna úloha materiálne mení čas dokončenia, označte to oddelene, nie korumpujte čas čítania.
• Bežné chyby — Autorstvo readingTime = 8, zabudnutie aktualizovať po prepise, prezentovanie falošnej presnosti, počítanie navigácie a boilerplate a považovanie vykonávaco náročného návodu za osem minút čítania plus žiadny čas na úlohu.

[[faq]]

• Účel — [[faq]] ukladá viditeľné páry otázok a odpovedí raz, aby stránka a akékoľvek oprávnené FAQ štruktúrované dáta nemohli od seba odísť.
• Typ a formát — TOML pole tabuliek; každá položka obsahuje jeden plain-text question a sebestačný reťazec answer.
• Povinný? — Podmienečný, keď po hlavnej stránke zostávajú skutočné doplňujúce otázky. Nikdy nie je povinný len na vyplnenie šablóny alebo dosiahnutie vyhľadávacej funkcie.
• Limity — Normálne štyri až osem užitočných položiek na stránkach playbooku. Každá otázka sa objaví raz a každá odpoveď musí byť kompletná bez spoliehania sa na poradie akordeónu.
• Kto alebo čo ho spotrebúva — Viditeľné vykreslenie FAQ, FAQPage schema kde je to oprávnené, navigácia stránky, QA obsahu a extrakcia odpovedí.
• Pravidlá — Toto je krížový referenčný kontrakt: nasledujte Prečo FAQ žije vo frontmatter a neskoršie pokyny pre FAQ namiesto udržiavania samostatných viditeľných a schema kópií. Ukladajte len otázky, ku ktorým má každý čitateľ prístup na stránke.
• Bežné chyby — Skryté odpovede len pre schému, duplicitné nadpisy maskované ako otázky, propagačné odpovede, nepodložené tvrdenia, zastarané JSON-LD a považovanie spôsobilosti na zobrazenie vo výsledkoch vyhľadávania za zaručenú.

[[lnks]]

• Účel — [[lnks]] zaznamenáva každý riadený interný odkaz použitý v tele, párujúc jeho viditeľnú kotvu s cieľom a udržiavaným popisom. Záznam robí odkazy skúmateľnými bez scrapovania vykresleného HTML a podporuje migráciu a QA.
• Typ a formát — TOML pole tabuliek s text, path a title. text je presná viditeľná kotva, path je URL relatívna k stránke s vedúcim a koncovým lomítkom a title je popis cieľovej stránky.
• Povinný? — Povinný pre každý interný odkaz v tele riadený touto konvenciou obsahu. Hĺbkové odkazy v aplikáciách a externé zdroje nasledujú svoje vlastné záznamy a nie sú maskované ako položky [[lnks]].
• Limity — Jeden záznam na výskyt odkazu v tele, keď rovnaká kotva môže smerovať na rôzne ciele; inak by mali byť presné duplicitné záznamy odstránené. Cieľ musí existovať alebo byť v schválenom registri kanonických slugov pre koordinované vydanie.
• Kto alebo čo ho spotrebúva — Validácia interných odkazov, migrácia obsahu, analýza vzťahov, generovanie názvov odkazov kde je podporované a redakčná kontrola.
• Pravidlá — Spárujte text s kotvou v tele doslovne, vrátane veľkých písmen a interpunkcie vo vnútri odkazu. Používajte kanonickú cestu relatívnu k stránke. Píšte title ako presný popis cieľa, nie ako inštrukcie pre aktuálnu stránku. Aktualizujte záznam a telo spoločne.
• Bežné chyby — Používanie dlhšej hodnoty text ako skutočná kotva, vymýšľanie neregistrovaného slugu, vynechanie koncového lomítka, zaznamenanie presmerovanej starej cesty, opisovanie zdroja namiesto cieľa a ponechanie záznamu po odstránení jeho odkazu z tela.

Povinné verzus voliteľné podľa typu príspevku

Matica aplikuje kontrakty uvedené vyššie na dvanásť typov príspevkov aktuálne deklarovaných týmto prvkom. R znamená povinný, C znamená podmienečný podľa pravidiel poľa, D znamená povinný výstup, ktorý môže byť bezpečne odvodený, a O znamená voliteľný. „Identita“ zahŕňa entity, id, title, type a stabilnú cestu. „Objavovanie“ zahŕňa description a keywords; ciele promptov zostávajú podmienečné pre každý riadok. aliases je vždy podmienečný pri presune, zatiaľ čo autorský čas čítania nie je nikdy povinný.

„Podmienečný recenzent“ nie je povolenie preskočiť recenziu tam, kde to presnosť alebo komerčné riziko vyžaduje. Stránky najlepšie-X a alternatívy vyžadujú nezávislú recenziu, pretože ich odporúčania môžu materiálne ovplyvniť rozhodnutie a často sa menia, ako sa menia produkty, ceny a spôsobilosť. Pre ostatné riadky aktivuje požiadavku politika rizika, nie dostupný čas editora. Rovnako, canonical označený D je stále povinný vo vykreslenom HTML; len frontmatter vstup môže byť vynechaný, keď šablóna môže generovať správnu self-referenciu.

Validácia frontmatter

Validácia by mala odmietnuť deterministické defekty automaticky a ponechať úsudok pre otázky, ktoré závisia na význame, dôkazoch alebo profesionálnej kompetencii. Rozdelenie zabraňuje dvom opačným zlyhaniam: žiadať recenzentov, aby chytili syntax, ktorú parser chytí dokonale, a predstierať, že pravidlo počtu znakov môže rozhodnúť, či je kópia čestná.

Spúšťajte deterministické kontroly pred redakčnou recenziou, aby recenzent videl koherentný záznam. Potom skontrolujte vykreslené HTML, nie len frontmatter: platná zdrojová hodnota je stále produkčný defekt, ak ju vybraná šablóna ignoruje, mapuje na nesprávny tag, skrýva požadovanú provenienciu alebo generuje canonical, ktorý nesúhlasí s verejnou cestou. Publikácia je kompletná len vtedy, keď sa zdroj, vykreslenie a správanie cieľa zhodujú.

Pole entity

entity odpovedá na otázku „aký presný typ príspevku je tento dokument inštanciou?“ Neodpovedá na otázku „akú tému táto stránka diskutuje?“ Tento rozdiel je dôležitý, pretože dva dokumenty môžu adresovať rovnakú tému, zatiaľ čo robia rôzne úlohy. Glosársky záznam definuje „diagnózu“; blogový článok môže hlásiť zmenu v diagnostickom usmernení. Ak obe používajú entity = "diagnosis", downstream systémy nemôžu spoľahlivo vybrať správnu šablónu, validačné pravidlá, analytickú skupinu alebo migráciu.

Použite predponu skupiny plus slug typu príspevku pre varianty v rámci rodiny: guide-how-to, guide-ultimate, comparison-a-vs-b a comparison-alternatives-to-x. Použite holý názov pre samostatný typ: product-page alebo case-study. Zaregistrujte identifikátor raz, udržujte ho stabilný a nikdy ho nemeňte, pretože sa zmení téma alebo cieľový dotaz. Umiestnite koncepty tém do taxonomy a jazyk dotazov do keywords.

Názov, H1 a SEO názov

Tieto hodnoty sa môžu líšiť podľa kontextu, ale musia opisovať rovnakú stránku. title je trvalá predvolená hodnota. h1 je viditeľný nadpis a môže byť prirodzenejší v kontexte. seoTitle slúži prehliadaču a výsledkom vyhľadávania a môže pridať stručný diferencátor, legitímny rok alebo príponu značky.

Napríklad title = "API Key Rotation", h1 = "How to Rotate an API Key Without Downtime" a seoTitle = "API Key Rotation: Safe Step-by-Step Guide" sú v súlade na jednej úlohe. „Free Security Tool“ ako SEO názov by bol klamlivý, pretože mení sľub. Nevytvárajte rozdiely len na vloženie viac kľúčových slov.

Pravidlá pre popis

Popis existuje, aby pomohol kvalifikovanému čitateľovi rozhodnúť sa kliknúť. Udržujte ho v rozmedzí 150–160 znakov, prirodzene zahrňte primárny termín, uveďte konkrétny prínos stránky a pridajte zmysluplný kvalifikátor ako publikum, rozsah alebo výsledok. Napíšte jednu plynulú vetu, nie zoznam kľúčových slov.

Termín potvrdzuje relevantnosť; opakovanie nepridáva hodnotu. Neduplikujte názov, nepoužívajte „Naučte sa všetko o“, nerobte nepodložené superlatívy ani nekončite v polovici myšlienky. Vyhľadávacie systémy môžu stále vybrať iný viditeľný text pre dotaz.

Dátumy, autori a recenzenti

date uchováva timestamp prvého publikovania. updated zaznamenáva poslednú podstatnú zmenu: faktickú opravu, nový dôkaz, zmenené inštrukcie, revidovaný rozsah, zmenené odporúčanie alebo kompletnú recenziu, ktorá potvrdzuje časovo citlivé tvrdenia. Zaznamenajte, čo sa zmenilo v redakčnej histórii, keď to politika vyžaduje.

Oprava interpunkcie, zmena štýlu tlačidla, prestavba šablóny alebo dotyk len timestampu neresetuje updated. Posunúť dátum bez práce za ním je porušením politiky, pretože hovorí čitateľom a strojom, že obsah bol obnovený, hoci nebol. Je to skreslenie, nie rastová taktika.

Polia autora a recenzenta nesú zodpovedné identity do tiráží a štruktúrovaných dát. Autor je zodpovedný za prácu. Používajte reviewedBy len vtedy, keď sa uskutočnila kvalifikovaná recenzia, a oba identifikátory prepojte s udržiavanými profilmi. Stránka základov dôvery vysvetľuje, ako autorstvo, dátumy, dôkazy a jasnosť entít podporujú dôveru bez zaručenia hodnotení.

Prečo FAQ žije vo frontmatter

FAQ je viditeľný obsah a štruktúrovaná kolekcia. Uloženie raz v [[faq]] umožňuje šablóne vykresliť akordeón a identické FAQPage JSON-LD, čím sa zabráni zastaranej skrytej schéme.

Zahrňte skutočné doplňujúce otázky viditeľné pre každého čitateľa. Neduplikujte nadpisy, neschovávajte propagácie v odpovediach ani neoznačujte nezobrazené otázky. Platné značkovanie negarantuje vyhľadávaciu funkciu.

Syntax a príklady kódu

Cross-platformový kontrakt mapuje polia, nie viditeľný komponent. Nasledujúca prenosná obálka je platná len v interchangesúbore, ktorého importer rozpoznáva direktívy metadát:

:::frontmatter{entity="guide-how-to" id="reset-api-key" title="How to Reset an API Key"}
description: Reset an API key safely, replace it in dependent services, verify it, and revoke the exposed key without avoidable downtime.
author: maya-chen
:::

Musí byť normalizovaná do natívnych metadát stránky počas importu. Nie je platná v tele produkčného článku. V Hugo je správne mapovanie TOML medzi +++ ohraničeniami na prvom byte, ako je uvedené v živom exemplári. Zámerne neexistuje shortcode {{< frontmatter >}}: shortcode by bežal príliš neskoro a v nesprávnom regióne dokumentu.

V WordPress mapujte rovnaké kanonické polia na registrované polia príspevku a post meta, napríklad post_title, post_excerpt, post_name, _amicited_entity, _amicited_author a _amicited_reviewed_by. Komentár ako <!-- wp:amicited/frontmatter --> alebo shortcode [frontmatter] je neplatný, pretože vytvára blok v tele namiesto metadát dokumentu. Importéri a editori môžu zobraziť panel metadát, ale uložené hodnoty musia zostať pripojené k záznamu príspevku.

Príklady

Dobrý: jeden koherentný, zodpovedný záznam

entity = "guide-how-to"
id = "rotate-api-key"
title = "How to Rotate an API Key"
description = "Rotate an API key safely, update every dependent service, verify the replacement, and revoke the old credential without avoidable downtime."
url = "/academy/rotate-an-api-key/"
date = "2026-08-27 10:00:00"
updated = "2026-09-03 14:30:00"
author = "maya-chen"
reviewedBy = "alex-rivera"
keywords = [ "rotate API key", "API key rotation", "revoke API key", "credential security", "API security", "secret rotation" ]
taxonomy = [ "security", "account-administration" ]
canonical = "https://amicited.com/academy/rotate-an-api-key/"

Toto identifikuje variant návodu, uchováva históriu, pomenúva zodpovedné osoby a oddeľuje tému od identity stránky. Dátum aktualizácie je podporený zdokumentovanou zmenou inštrukcie a recenziou.

Zlý: názov zopakovaný ako popis

title = "How to Rotate an API Key"
description = "How to Rotate an API Key"

Popis nepridáva žiaden prínos, rozsah ani dôvod na kliknutie. Tiež plytvá priestorom ukážky, ktorý by mohol odlíšiť túto stránku od každého iného výsledku používajúceho rovnaký názov.

Zlý: jedna entita znovu použitá naprieč dvoma typmi príspevkov

# glosársky záznam
entity = "diagnosis"

# redakčný sprievodca
entity = "diagnosis"

Zdieľaná téma nahradila identitu typu príspevku. Použite registrované hodnoty ako glossary-term a guide-ultimate, potom priraďte „diagnosis“ cez taxonómiu alebo kľúčové slová.

Zlý: dátum aktualizácie bez diffu obsahu

date = "2026-01-15 09:00:00"
updated = "2026-08-27 10:00:00" # zmenil sa len dátum

Žiadna podstatná úprava alebo recenzia nepodporuje tvrdenie o čerstvosti. Nechajte updated nezmenený alebo vynechaný, kým neexistuje skutočná zmena, ktorú možno skontrolovať v redakčnej histórii.

Značkovanie schémy a prístupnosť

Metadáta poskytujú hodnoty; šablóna zostáva zodpovedná za sémantické HTML, fókus, kontrast, účel odkazov a alternatívny text.

Pravidlá písania

• Udržiavajte identifikátory stabilné, malé písmená a bezpečné pre stroje. Nikdy nerecyklujte id alebo ticho nemeňte entity po publikácii.
• Používajte plain text v poliach podobných názvu. HTML, Markdown odkazy, emoji dekorácie a vynútené zalomenia riadkov nepatria do reťazcov metadát.
• Udržujte popis na 150–160 znakov a polia kľúčových slov na šesť až osem odlišných fráz pre tento playbook.
• Používajte skutočné registrované osoby pre polia autora a recenzenta. Nikdy nevytvárajte ceremoniálneho recenzenta alebo generickú identitu „Redakčný tím“, pokiaľ nejde o udržiavanú zodpovednú entitu.
• Používajte riadenú taxonómiu. Varianty pravopisu a duplicity jednotného/množného čísla vytvárajú fragmentované archívy.
• Referencujte len obrázky, ktoré existujú a majú publikačné práva. imageAlt opisuje informatívny obsah obrázku, nie jeho SEO cieľ.
• Udržujte FAQ odpovede priame a sebestačné. Tvrdenia stále vyžadujú rovnaký dôkaz a zverejnenie ako próza inde na stránke.
• Nikdy neumiestňujte tajomstvá, súkromné poznámky, access tokeny, embargované inštrukcie, osobné údaje alebo nerecenzované právne nároky do publikovateľného frontmatter.

Ktoré typy príspevkov používajú frontmatter a kde

Každý typ príspevku používa frontmatter na prvom byte. Požadovaná hĺbka sa mení s rizikom, zámerom a schémou, nie s vizuálnym dizajnom.

QA kontrolný zoznam

• Začína súbor s +++, obsahuje platné TOML a uzatvára záznam pred obsahom tela?
• Je entity registrovaný presný identifikátor typu príspevku, nie téma, kampaň alebo názov stránky?
• Je id jedinečné a stabilné a zodpovedá url registru kanonických slugov?
• Opisujú title, voliteľné h1 a voliteľné seoTitle rovnakú stránku bez klamlivých zmien rozsahu?
• Je popis 150–160 znakov, obsahuje prirodzene primárny termín a ponúka konkrétny dôvod na kliknutie?
• Existuje každý referencovaný obrázok a je imageAlt presný pre obrázok, ktorý sa vykresľuje?
• Je dátum publikácie zachovaný a je každá hodnota updated podporená podstatným diffom alebo dokumentovanou recenziou?
• Riešia sa identifikátory autora a recenzenta na skutočné udržiavané profily a recenzoval uvedený recenzent skutočne prácu?
• Sú kľúčové slová obmedzené na šesť až osem užitočných fráz a hodnoty taxonómie čerpané z riadených slovníkov?
• Používa canonical HTTPS, smeruje na preferovanú stránku a súhlasí s mapou stránok a internými odkazmi?
• Obsahuje každá položka [[faq]] jednu užitočnú otázku a sebestačnú odpoveď, ktoré sa vykreslia viditeľne v identickom znení?
• Zodpovedá generovaný JSON-LD viditeľnému obsahu, používa stabilné identifikátory a prechádza syntaktickou validáciou bez nárokovania nepodporovaných typov?
• Chýbajú v zázname tajomstvá, súkromné redakčné poznámky, nepodložené tvrdenia a zverejnenia určené len pre telo?

FAQ

Je frontmatter viditeľný na publikovanej stránke?

Zdrojový záznam je skrytý, ale šablóny môžu vykresliť názov, osoby, dátumy a FAQ. Ostatné polia napájajú ukážky, kanonické značky, kanály, mapy stránok, schému a interné systémy.

Má pole entity obsahovať tému alebo typ príspevku?

Identifikuje presný typ príspevku. Zdieľané témy patria do taxonómie a kľúčových slov, nie na miesto identity dokumentu.

Môžu byť názov, H1 a SEO názov odlišné?

Áno. H1 môže znieť prirodzenejšie a SEO názov môže pridať diferencátor, ale všetky verzie musia dávať rovnaký sľub.

Kedy by sa mal zmeniť dátum aktualizácie?

Zmeňte ho po podstatnej faktickej recenzii alebo úprave. Nemeňte ho pre interpunkciu, štýlovanie, prácu na šablóne alebo obnovu len dátumu.

Prečo sú otázky FAQ uložené vo frontmatter?

Štruktúrované pole umožňuje jednému zdroju vykresliť viditeľné FAQ aj zodpovedajúce FAQPage JSON-LD. To zabraňuje odchýleniu schémy od toho, čo čitatelia môžu skontrolovať.