All guides › By use case

A changelog with pictures and docs that keep up with the app

CHANGELOG.md and the guides in your docs folder show screens from accepted runs. When a screen changes, Kaloko says which section to rewrite.

Support asks what changed in the release. The answer is a list of pull request titles nobody outside the team can read, and the help centre still shows the checkout from two versions ago. Your accepted runs already hold every screen of the release, so the changelog and the docs can show them.

The problem

Screenshots in documentation are taken by hand, once, and go stale with the next release. Release notes are written from commit messages. Nobody notices that a guide describes a button that moved until a customer writes in.

What changes with Kaloko

A picture in Markdown names a step instead of a file: !Payment shows the newest accepted screenshot of that step, ?version=2.4.0 the one of that release. The changelog and the guides stay in your repository; Kaloko turns the references into pictures and shows them as pages you can share with clients, support or marketing.

How it works

1. Set it up once

   npx kaloko init --docs=changelog adds CHANGELOG.md and the config block; --docs=full also creates docs/ folders for tutorials, how-to guides, reference and explanation, each with a template.

2. Draft the entry

   kaloko changelog draft writes the Unreleased entry from the merged pull requests since the last release and adds before and after pictures of the screens accepted runs show differently. --apply writes it into CHANGELOG.md; the agent then rewrites the lines for people.

3. Record the release

   kaloko release 2.4.0 turns Unreleased into the version, records its pictures and prints the changelog page. With release-please, changesets or semantic-release, kaloko ci github --release adds a workflow that does it on every published release.

4. Keep the guides current

   kaloko docs publish sends the docs folder to Kaloko. When an accepted run later shows a different screen, the section says "the screen changed in 2.4 — check the text", and kaloko docs check lists it, with broken references and missing translations, and exits 1 in CI.

5. Export where you need it

   kaloko export --format md|docusaurus|vitepress|mkdocs|html|pdf|json writes the docs and the changelog with the pictures as files for your own docs site.

Skills and prompts

Draft the changelog entry for this release with Kaloko, rewrite the lines for our customers and keep the before and after pictures.

Expected outcome: an Unreleased entry grouped Added, Changed, Fixed, Removed, one change per line, with step references under the lines they show. Nothing is recorded until you say so.

Run kaloko docs check and fix every section whose screen changed since it was written; translate the changes into Czech too.

Expected outcome: the stale sections rewritten against the new screens, guide.cs.md files updated next to the originals, and a clean kaloko docs check.

What you get

• A changelog page with a slider between before and after, in the reader's language and screen size, each picture linked to its flow on the canvas.
• Guides that play as a walkthrough, one step at a time, with a version selector, search and language switch.
• On every plan: the changelog, the latest docs and Markdown or JSON exports. From Business: docs per version with stale sections, the static-site, HTML and PDF exports, a "What's new" e-mail with each release, readers from your company's domain and a public changelog with a feed.

FAQ

More guides