What Are the Common Use Cases for Kroki?

Updated

Kroki turns textual descriptions into diagrams, so its main use cases all share one trait: the diagram source lives as text you can store, review, and regenerate. The most common situations are embedding diagrams in Markdown or AsciiDoc documentation, generating diagrams automatically in a CI/CD pipeline, collaborating on diagrams through version-controlled text, and avoiding GUI diagramming tools when you want a faster, scriptable workflow. If your diagram needs to be edited by hand in a visual editor or exported as a polished graphic for print, Kroki is a weaker fit.

Embedding diagrams in documentation

Kroki's site describes itself as creating "diagrams from textual descriptions," and its examples and diagram-type sections show that the input is a text block rather than a binary file. That makes it natural for docs written in Markdown, AsciiDoc, and similar formats.

The typical pattern:

  1. Write a diagram definition in a supported text syntax (for example a PlantUML, Mermaid, or Graphviz block).
  2. Reference it from your document, either by pointing at a Kroki URL or by using a plugin/extension that calls Kroki.
  3. The rendered image appears in the built documentation.

Why this matters: the diagram source sits next to the prose in the same file or repo, so a change to the architecture description and the diagram can be reviewed in one commit.

Automating diagram generation in CI/CD

Because the input is text, diagram rendering can be a build step rather than a manual export.

A workable pipeline looks like this:

  • Diagram source files are committed to the repository.
  • The CI job sends each source to Kroki (or to a self-hosted Kroki instance) and receives an image.
  • The generated image is published alongside the docs or attached to a release.

The payoff is that diagrams can't silently drift out of date: if the source changes, the next build regenerates the image. The trade-off is that the build now depends on Kroki being reachable, which is why teams that need offline or air-gapped builds often run their own instance instead of the public service.

Collaborating through text instead of a GUI

When several people maintain the same diagram, a text format is easier to diff and merge than a binary file from a drawing tool. A pull request that changes a node or an edge shows up as a readable line change.

This is the strongest argument for Kroki in team settings:

  • Reviewers can comment on specific lines of the diagram definition.
  • Merge conflicts are resolvable in text.
  • History shows who changed what and when.

The limitation is that non-technical contributors may find the syntax harder than dragging boxes in a GUI editor.

Choosing between Kroki and a GUI tool

Dimension Kroki (text-based) GUI diagramming tool
Source of truth Plain text, version-controllable Often a binary or proprietary file
Automation Scriptable, fits CI/CD Usually manual export
Collaboration Diffs and merges in text Harder to review changes
Learning curve Requires knowing a diagram syntax Visual, often easier to start
Best for Docs-as-code, repeatable builds One-off polished graphics

Pick Kroki when the diagram is part of a maintained codebase and you want it regenerated automatically. Pick a GUI tool when the diagram is a one-off visual that needs fine manual layout control.

When Kroki is not the right choice

  • You need pixel-level manual positioning that text syntax can't express.
  • Your build environment can't reach a Kroki instance and you don't want to host one.
  • The people maintaining the diagram won't work in text.

For everything else — documentation diagrams, architecture sketches kept in a repo, and diagrams that should update with the code — Kroki's text-to-diagram model is the reason to use it.