Formát obsahu – MD definice stránek

Obsah tohoto webu žije v Markdown souborech uvnitř repozitáře – bez databáze, bez CMS a bez administrace. Závazný tvar určuje ADR-0011 (schéma obsahu) a ADR-0012 (jazykové mutace). Build soubory načte, zvaliduje a vykreslí do statického HTML. Neznámé pole, chybějící povinná hodnota nebo překlep v řídicím prefixu stavbu zastaví, aby se chyba nemohla publikovat.

Kde obsah leží

obsahová položka – adresář content/ygg/explore/<slug>/: jazykově neutrální metadata v item.md, překlad v cs.md a en.md
statická stránka – content/ygg/pages/<slug>/cs.md a en.md
přílohy položky – content/ygg/explore/<slug>/assets/

Adresář je slug, název souboru je jazyk. Ani jedno se proto neuvádí ve frontmatteru – obojí je ohlášená chyba. Pole, které se nepřekládá (typ, data, témata, vazby), patří do item.md jednou pro celou položku; mutace nese jen přeložená pole a tělo. Pole na špatném místě je chyba. Mutace se párují adresářem: chybí-li en.md, anglická adresa prostě neexistuje. Překlad se nikdy nepředstírá českým textem.

Frontmatter položky

Povinná pole jsou type, topics, date a published v item.md a title a tags v mutaci. Úplný seznam polí s jejich místem je v content/ygg/explore/FIELDS.md.

type – jedna z osmi hodnot guide, troubleshooting, reference, explainer, analysis, note, link, project. Určuje ikonu, řazení i adresu: návod má /navod/<slug>/, problém /problem/<slug>/.
topics – číselník témat; volné klíčové slovo patří do tags.
status – číselník stavů, který se zobrazí v panelu položky.
date, updated, verified, published, dataTo – vždy ISO RRRR-MM-DD. Tvar MM/RRRR je jen formát zobrazení, nikdy formát zápisu.
published – datum zveřejnění řadí proud a určuje ročník archivu; budoucí datum znamená naplánováno, false drží položku mimo výpisy.
volitelně dále summary, desc, hero, toc, numbering, scope, environment, difficulty, level, duration, reading, prereqs, sources, sourcesCount, related, callout, calloutLabel, url, source, from, stack, featured, order, assets, embeds, sections.
dev_only: true drží položku jen ve vývoji – mimo build, mapu webu, feedy i hledání. Rozepsaný text se značí status: draft.
redirect_from je povinné, jakmile se změní už zveřejněná adresa; build z něj vydá přesměrování.

Rozhoduje obsah polí, ne typ záznamu: co není vyplněné, se nevykreslí. Prázdná hodnota, null a pomlčka — znamenají totéž – nevyplněno.

Tělo položky

Tělo je Markdown rozšířený o uzavřenou množinu řídicích prefixů:

## Nadpis je sekce, ### Nadpis podsekce; kotva vzniká ze slugu nadpisu
nav: zkrácený popisek sekce do bočního obsahu – smí stát jen hned za nadpisem
command: řádek příkazu
note: a warning: poznámka a varování
- odrážka, -! zvýrazněná odrážka, 1. číslovaný seznam
ohraničený blok kódu; jazyk output z něj udělá blok výstupu, ne vstupu
| klíč | hodnota | je dvousloupcová tabulka; jsou-li klíče data, vykreslí se jako časová osa
![popis](soubor.png) obrázek – alt text je povinný, dekorativní obrázek do obsahu nepatří

Prefix mimo tento seznam je chyba, ne text k vykreslení. Překlep waring: by se jinak tiše publikoval jako odstavec.

Typografie

Text se píše znaky z klávesnice: rovnými uvozovkami a spojovníkem. Build je převede podle jazyka – česky na „…“, anglicky na “…”, spojovník mezi slovy na pomlčku a rozsah let na pomlčku bez mezer. Kód, příkazy, HTML značky a adresy zůstanou beze změny. Typografický znak zapsaný ručně je chyba kontroly, aby zdroj nenesl dvě konvence.

Statická stránka

Statická stránka má dvě podoby a obě jsou platné:

čtecí – jako tahle stránka: frontmatter nese kicker, title, volitelně lead a updated, obsah je celý v těle
strukturovaná – jako O mně, Práce nebo Věci veřejné: pole sections ve frontmatteru řídí pořadí a tvar pásů, dlouhé texty leží v těle za značkou

Typy sekcí jsou text, grid, list, index, states, steps, chips, keyvals, stat, kontakt, callout a featured-projects. Poslední jmenovaná se nevyplňuje ručně – vzniká z kolekce projektů. Většina sekcí drží data v poli items; keyvals je má ve skupinách groups a chips smí pod odznaky přidat links. Sekce bez svých dat by byla prázdný pás, takže ji validace odmítne. Interní cíl se v sekci adresuje linkRoute (id z tabulky cest) a položka seznamu slugem; hotová cesta do obsahu nepatří, protože ji vlastní tabulka cest a jazyk k ní doplní build.

Obě podoby se nemíchají. Nadpis v těle strukturované stránky by byl druhá, neřízená struktura vedle sections, a validace ho odmítne.

Bezpečnost a kontrola

Raw HTML je omezené na details, summary, figure, figcaption, abbr, mark, kbd, sub a sup, atribut open jen na details a title jen na abbr. Cokoli dalšího se vypíše jako text, ne jako značka.

Přílohy se evidují v poli assets s path, origin, creator a license; cizí materiál navíc s source_url. Cesta musí být relativní a bez ...

Celý strom kontroluje příkaz make content-check – stejná validace, jakou používá build. Chyba se hlásí i s cestou k poli, ne jen jménem souboru.