Formát site.json

Soubor site.json představuje kompletní deklarativní předpis celého webu jedné školy v jediném dokumentu. Společně s připojeným adresářem media/ obsahuje veškerá data nutná k sestavení webu: identitu školy, kontaktní údaje, vizuální styl a písma, hlavní menu, kategorie článků, strom stránek složených ze sekcí, aktuality i katalog multimediálních souborů.

Formát slouží jako závazný kontrakt mezi přípravou obsahu (člověk nebo jazykový model pracující se vstupy školy) a systémem Než zazvoní CMS. Stejný formát se využívá při migraci z WordPressu, při automatizovaném zakládání nových škol i pro budoucí strojové úpravy obsahu.

Základní principy formátu

Formát je striktně verzován (version: 1). Pravidla a datové typy definuje formální schéma JSON Schema (draft 2020-12) v souboru tools/site.schema.json.

Pravidla kontraktu:

1. Uzavřená specifikace: Schéma zakazuje neznámá pole (additionalProperties: false), překlepy validátor okamžitě odhalí.
2. Přísné enumerace: Výběry ikon, variant zobrazení, barevných pozadí i písem jsou pevně vyjmenovány.
3. Pravidlo pro rich text: Formátovaný text se zapisuje jako zjednodušený Markdown (odstavce, nadpisy, seznamy, citace, tučné písmo, kurzíva, odkazy) nebo jako hotové bloky Strapi Blocks. Markdown se při importu převádí na bloky, přičemž nejvyšší nadpis # se automaticky snižuje na H2 (nadpis H1 nese výhradně titulek stránky nebo sekce Hero).
4. Odkazování na média: Obrázky a dokumenty se odkazují řetězcem media:<klíč>, například media:hero/uvod.jpg. Klíč musí přesně odpovídat položce v seznamu médií a fyzickému souboru na disku.
5. Délkové limity: Schéma hlídá maximální délky textů (nadpis karty do 80 znaků, text karty do 400 znaků, titulek sekce Hero do 160 znaků).

Struktura kořenového objektu

Kořenový objekt souboru site.json obsahuje následující vlastnosti:

Pole	Datový typ	Povinné	Popis
version	číslo	Ano	Verze formátu, hodnota 1
$schema	řetězec	Ne	URL adresa JSON schématu (https://nezzazvoni.cz/schema/site-v1.json)
meta	objekt	Ne	Informace o vzniku souboru, do CMS se neukládá
school	objekt	Ano	Identita školy, kontakty, vzhled, barvy a menu
categories	pole	Ne	Seznam kategorií aktualit
pages	pole	Ano	Seznam všech stránek webu (minimálně 1 stránka)
posts	pole	Ne	Seznam článků a aktualit
media	pole	Ne	Seznam multimediálních souborů a dokumentů

Podrobný popis částí souboru

Nastavení školy (school)

Objekt school definuje identitu celé školy a jejího webu:

• Identita: Povinná pole name (oficiální název) a slug (zkratka v adrese, například oapv). Volitelně shortName (zkrácený název), domain (doména bez protokolu a bez www, například oapv.cz) a tagline (slogan a popis pro vyhledávače).
• Vzhled a značka: design (klasik nebo nz), logo (media:<klíč>), brandMark (vodoznak), headerImage (fotka podstránek) a theme (barvy colorPrimary, colorAccent, colorDark, colorSurface, písma fontHeading, fontBody, zaoblení radius).
• Kontakty a úřední údaje: Pole address, phone, email, ico (8 číslic), redizo (9 číslic), dataBox (7 znaků), sítě facebook, instagram, youtube.
• Navigace a lišty: menu (položky s label, url, children), announcement a announcementLink (informační lišta), utilityLinks (rychlé odkazy nad menu, max. 8).
• Testovací pole: compareUrl a compareLabel pro přepínač verzí.

Kategorie článků (categories)

Objekty kategorií aktualit obsahují název name a unikátní identifikátor slug (například sport, ze-zivota-skoly).

Stránky webu (pages)

Pole pages obsahuje jednotlivé stránky webu:

• path: Celá adresa bez úvodního a koncového lomítka (např. o-skole/historie). Úvodní stránka má cestu "" nebo isHomepage: true. Hierarchie stránek se odvozuje z lomítek.
• title: Název stránky (hlavní nadpis a název v rozcestnících).
• slug: Poslední část adresy (odvodí se z cesty).
• order: Číslo určující pořadí v rozcestnících a navigaci.
• showInNav: Příznak zobrazení v rozcestnících (výchozí true).
• excerpt: Perex (do 400 znaků) pod nadpisem stránky.
• cover: Náhledový obrázek (media:<klíč>) pro dlaždice.
• status: Stav publikace: published nebo draft.
• sections: Pole komponent sekcí.

Katalog sekcí (sections)

Každá sekce v poli sections nese povinnou vlastnost type, kterou importér mapuje na komponentu Strapi section.<type>.

Dostupných je 19 typů sekcí rozdělených podle účelu:

• Prezentace a úvod: hero (vstupní sekce složené stránky s H1), text (formátovaný text v poli body), text-image (text s fotografií), cta (výzva k akci), buttons (řada tlačítek).
• Strukturované informace: cards (mřížka karet v 2 až 4 sloupcích), stats (číselné statistiky se štítky), dates (termíny událostí), steps (číslované kroky), table (tabulka se záhlavím a řádky).
• Reference a dotazy: testimonials (citace s fotkou), faq (otázky a odpovědi s JSON-LD), accordion (rozbalovací položky).
• Média a dokumenty: gallery (fotogalerie), documents (dokumenty ke stažení), embed (mapa, YouTube video či Facebook).
• Kontakty a výpisy: contact (kontakty a medailonky osob), posts (výpis aktualit podle kategorie), logos (loga partnerů).

Na následujícím snímku vidíte výběr komponent sekcí v administraci, které přímo odpovídají typům sekcí v souboru site.json:

Články a média

Články v poli posts obsahují povinná pole slug, title, date (datum v ISO formátu) a volitelná pole category, cover, excerpt, content, attachments, gallery, status a legacyId.

Pole media deklaruje soubory webu: povinný identifikátor key (například hero/uvod.jpg), volitelnou cestu file (výchozí media/<key>), MIME typ mime, alternativní text alt (do 300 znaků) a popisek caption.

Validace pomocí nástroje validate-site.mjs

Před nahráním do CMS se provádí kontrola integrity nástrojem validate-site.mjs:

node tools/validate-site.mjs <cesta k adresáři se site.json>

Přepínač --strict zastaví proces i při pouhém varování:

node tools/validate-site.mjs data/skoly/oapv --strict

Nástroj prověřuje shodu se schématem, jedinečnost adres path a slug, existenci právě jedné úvodní stránky (path: ""), existenci nadřazených stránek, vazby na kategorie, existenci odkazovaných souborů na disku, interní odkazy v navigaci i převoditelnost Markdownu do Strapi Blocks.

Návratový kód 0 znamená úspěch, kód 1 značí chybu.

Režimy importu do CMS

Nahrání dat zajišťuje skript cms/scripts/import-site.js spouštěný v kontejneru:

node scripts/import-site.js <adresář se site.json a media/> [--update | --reset]

Podporované režimy:

1. Výchozí režim (založení nové školy): Bez přepínačů skript očekává novou školu. Pokud škola se zadaným slugem nebo kořenová složka médií již existuje, import skončí chybou.
2. Režim doplnění (--update): Provádí bezpečný upsert obsahu existující školy podle přirozených klíčů (cesta stránky, slug článku, klíč média). Nic nemaže, existující média se znovupoužijí bez nového nahrávání.
3. Režim nového startu (--reset): Kompletně vymaže stávající obsah školy (stránky, články, kategorie i soubory ve složce školy) a nahraje web znovu z čistého stavu.

Z hostitelského systému lze celou akci provést jedním příkazem:

tools/nova-skola.sh data/skoly/zs-priklad redaktor@zspriklad.cz

Tento skript na hostiteli ověří site.json validátorem, přenese data do kontejneru CMS a spustí založení školy, složky médií, role, pozvánky redaktora i import obsahu.

Tipy a doporučení

Iterativní výroba s AI modelem

Při generování obsahu jazykovým modelem využijte uzavřenou smyčku: model vygeneruje site.json, validátor zkontroluje výsledek a chyby model obratem opraví.

Složená úvodní stránka

Aby se úvodní stránka školy vykreslila v moderním složeném rozvržení od okraje k okraji, musí mít prázdnou adresu path: "" a její první sekcí musí být komponenta hero.

Relativní cesty k médiím

Všechny soubory v adresáři media/ musejí mít cesty relativní k umístění souboru site.json a nesmějí odkazovat mimo adresář školy.

Související

• Veřejné REST API
• Webový frontend
• Založení nové školy
• Katalog sekcí