Publish living docs and catch stale sections

Guides in your repository can show the screens of your accepted runs instead of pasted screenshots, so their pictures never go stale. When a screen changes after the text was written, Kaloko tells you which section to check. The pages you are reading now are made this way: kaloko.app/p/sinfin/kaloko/docs.

Set up the folder

npx kaloko init --docs=full

It creates docs/ with the four Diátaxis folders, each with a template:

FolderThe reader wants
tutorials/to learn by doing, start to finish
how-to/to get one task done
reference/to look a fact up
explanation/to understand why

index.md is the start page. Front matter is optional: title (else the first heading) and order (the position in the sidebar). Link pages with relative .md links.

Write a page

Pictures are step references, as in the changelog:

1. Choose **Sign in** in the top bar.
   ![The sign-in page](kaloko:KALOKO-public/login)

A translation sits next to its original: pay.cs.md beside pay.md, with the languages listed in the config (docs.languages: [en, cs], originals first). Pictures follow the language of the text.

Some things are easier to watch than to read: a drag and drop, a dialog that opens, a language switch. When the accepted run has a recording of the step (kaloko walk --record), the picture shows a play button; a click or a tap plays the recording without sound and the picture comes back at the end. Nothing plays by itself. Add ?media=video to say that a step needs its recording (kaloko docs check warns when the run has none), or ?media=image to keep just the picture:

![Translate a category](kaloko:DOC-console/category-edit?media=video)

Recordings that your docs or changelog play are kept for as long as they play them, and they count in storage.

Show one part of a screen

A whole screen is often too much when the text talks about one button. Name the parts a guide needs in the scenario, under the step's details:, and every walk takes them in each language and screen size, masked like the screenshot:

- id: cart
  title: Cart
  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: Order summary
      selector: .summary .total
      context: section

Kaloko shows the element with the part of the page around it and draws a ring around the element. Without context that part is the nearest section or card of at least 480 × 240 px (narrower on a phone); context: card, context: section, context: page (one screen around it) or a CSS selector of an ancestor choose it yourself, and padding adds room (16 px by default). A long section is cut to one screen around the element. states: [error] takes a detail only in some states of the step.

In the text, add the id after #:

2. Choose **Add to cart**.
   ![Add to cart](kaloko:shop/cart#add-to-cart)

The other parameters work as before (kaloko:shop/cart?locale=cs#add-to-cart). The canvas lists the details of a step under Step attachments on the Page tab, each with its reference. Until an accepted run has the detail, readers see the whole screen and kaloko docs check warns.

One action per list item with its picture right under it also makes the page a walkthrough: readers choose Walk through it step by step and see one step at a time, and can tick I tried it.

Publish

npx kaloko docs publish                     # the docs of latest
npx kaloko docs publish --version 2.4.0     # the docs of a release (Business)

Readers get a version selector, language and screen switches and search, and every picture opens its step on the canvas. kaloko release publishes the docs folder for its version on its own unless you pass --no-docs. Who reads the docs follows the same rules as the changelog: see Publish a changelog with pictures.

Catch stale sections

When you publish, Kaloko remembers the screen behind every reference. When a later accepted run shows a different screen, the section says "The screen changed in 2.4 — check the text." to the people who write the docs (Business).

npx kaloko docs check             # against the published docs; needs a token
npx kaloko docs check --offline   # only the local files

Errors: broken references, steps the scenario files do not have, references without an accepted picture and stale sections. Warnings: missing or outdated translations, changelog items that people will see but that have no picture, media=video references whose accepted run has no recording of the step, and #detail references that the scenario does not declare or that no accepted run has yet. The command exits with 1 on errors; --strict also on warnings, which suits CI.

For each stale section, open the step, compare it with the text and rewrite what no longer fits; the note clears at the next kaloko docs publish. If the text still fits, kaloko docs publish --reviewed clears the notes without a change. Use it only after you have read them.

To get the docs out as files for another site, see Export docs and the changelog.

Kaloko · latest · 2026-11-21