Publikovat živou dokumentaci a hlídat zastaralé části
Návody ve vašem repozitáři můžou místo vložených screenshotů ukazovat obrazovky z přijatých běhů, takže obrázky nikdy nezestárnou. Když se obrazovka po napsání textu změní, Kaloko řekne, kterou část zkontrolovat. Stránky, které právě čtete, vznikají přesně takhle: kaloko.app/p/sinfin/kaloko/docs.
Připravte složku
npx kaloko init --docs=full
Vytvoří docs/ se čtyřmi složkami podle Diátaxis, v každé šablonu:
| Složka | Čtenář chce |
|---|---|
tutorials/ | naučit se to od začátku do konce |
how-to/ | udělat jeden konkrétní úkol |
reference/ | dohledat fakt |
explanation/ | pochopit proč |
index.md je úvodní stránka. Front matter je nepovinný: title (jinak první nadpis) a order (pořadí v postranním menu). Stránky propojujte relativními odkazy na .md.
Napište stránku
Obrázky jsou odkazy na kroky, stejně jako v changelogu:
1. V horní liště zvolte **Přihlásit**.

Překlad leží vedle originálu: pay.cs.md vedle pay.md, jazyky vyjmenuje konfigurace (docs.languages: [en, cs], jazyk originálů první). Obrázky se řídí jazykem textu.
Některé věci je lepší vidět než číst: přetažení, dialog, který se otevře, přepnutí jazyka. Když má přijatý běh záznam kroku (kaloko walk --record), je na obrázku tlačítko pro přehrání. Kliknutí nebo klepnutí záznam přehraje bez zvuku a na konci se vrátí obrázek. Samo se nic nepřehrává. Přidejte ?media=video, když krok svůj záznam potřebuje (kaloko docs check upozorní, když ho běh nemá), nebo ?media=image, když má zůstat jen obrázek:

Záznamy, které vaše dokumentace nebo changelog přehrávají, zůstanou, dokud je přehrávají, a počítají se do úložiště.
Ukažte jen část obrazovky
Když text mluví o jednom tlačítku, celá obrazovka je často zbytečně velká. Části, které návod potřebuje, pojmenujte ve scénáři u kroku pod details:. Každý běh je pak vyfotí ve všech jazycích a velikostech obrazovky a osobní údaje v nich skryje stejně jako na snímku:
- id: cart
title: Košík
path: /cart
details:
- id: add-to-cart
name: { en: Add to cart button, cs: Tlačítko Přidat do košíku }
selector: "#add"
- id: summary
name: Souhrn objednávky
selector: .summary .total
context: section
Kaloko ukáže prvek i s okolím a obtáhne ho rámečkem. Bez context je okolím nejbližší sekce nebo karta, která má aspoň 480 × 240 px (na telefonu méně). context: card, context: section, context: page (jedna obrazovka kolem prvku) nebo CSS selektor nadřazeného prvku ho určí přesně a padding přidá okraj (výchozí 16 px). Dlouhou sekci Kaloko ořízne na jednu obrazovku kolem prvku. states: [error] vyfotí detail jen v některých stavech kroku.
V textu přidejte id za #:
2. Zvolte **Přidat do košíku**.

Ostatní parametry fungují dál (kaloko:shop/cart?locale=cs#add-to-cart). Na plachtě najdete detaily kroku v Přílohách kroku na kartě Stránka, každý i s odkazem. Dokud detail není v žádném přijatém běhu, čtenáři vidí celou obrazovku a kaloko docs check upozorní.
Když má každá položka seznamu jednu akci a obrázek hned pod sebou, dá se stránka projít i jako průvodce: čtenář zvolí Projít krok za krokem, vidí vždy jeden krok a může si odškrtnout Mám vyzkoušeno.
Publikujte
npx kaloko docs publish # dokumentace pro latest
npx kaloko docs publish --version 2.4.0 # dokumentace vydání (Business)
Čtenáři dostanou výběr verze, přepínač jazyka a obrazovky a hledání a každý obrázek otevře svůj krok na plachtě. kaloko release publikuje složku s dokumentací pro svou verzi sám, pokud nepřidáte --no-docs. Kdo dokumentaci čte, se řídí stejnými pravidly jako changelog: viz Publikovat changelog s obrázky.
Hlídejte zastaralé části
Při publikování si Kaloko zapamatuje obrazovku za každým odkazem. Když pozdější přijatý běh ukáže jinou obrazovku, uvidí lidé, kteří dokumentaci píšou, u části poznámku „Obrazovka se změnila ve verzi 2.4 — zkontrolujte text.“ (Business).
npx kaloko docs check # proti publikované dokumentaci; potřebuje token
npx kaloko docs check --offline # jen lokální soubory
Chyby: rozbité odkazy, kroky, které scénáře nemají, odkazy bez přijatého obrázku a zastaralé části. Varování: chybějící nebo neaktuální překlady, položky changelogu, které lidé uvidí, ale nemají obrázek, a odkazy s media=video, jejichž přijatý běh záznam kroku nemá, a odkazy na #detail, který scénář nemá nebo který zatím žádný přijatý běh nevyfotil. Při chybě příkaz skončí kódem 1; s --strict i při varování, což se hodí do CI.
U každé zastaralé části otevřete krok, porovnejte ho s textem a přepište, co už nesedí; poznámka zmizí při dalším kaloko docs publish. Pokud text pořád sedí, kaloko docs publish --reviewed poznámky smaže beze změny textu. Použijte ho, až když jste je přečetli.
Jak dokumentaci dostat ven jako soubory pro jiný web: Exportovat dokumentaci a changelog.
Kaloko · latest · 2026-11-21