Dokumentace

Kaloko

Stáhnout
Markdown s obrázky (.zip)Složka pro Docusaurus (.zip)Složka pro VitePress (.zip)Složka pro MkDocs (.zip)HTML pro offline čtení (.zip)PDFNovinky jako JSON
Stránky
▶ Projít krok za krokem

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řihlašovací stránka](kaloko:KALOKO-public/login)

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:

![Přeložit kategorii](kaloko:DOC-konzole/category-edit?media=video)

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**.
   ![Přidat do košíku](kaloko:shop/cart#add-to-cart)

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.

Na této stránceNa této stránce