How to Create a Diagram with Kroki

Updated

Kroki turns a textual description into a rendered diagram. To create one, open kroki.io, pick a diagram type, write the description in that type's syntax, and let the service render it — then copy the resulting image or link. This works for anyone who can write the source syntax; no local installation is required to use the hosted service.

What you need before you start

  • A diagram description written in a supported syntax (for example, a PlantUML, Mermaid, Graphviz, or other supported diagram language).
  • Access to kroki.io in a browser, or a way to call the Kroki service from your own tools if you want to automate rendering.
  • A clear idea of the diagram you want, since Kroki renders what the text describes rather than offering a drag-and-drop canvas.

Steps to create a diagram

1. Open Kroki and choose a diagram type

Go to kroki.io. The site is built around the idea of creating diagrams from textual descriptions, and it lists the diagram types it supports along with examples and a cheat sheet. Use those sections to confirm the syntax family you want before writing anything.

2. Write your diagram description

Enter your source text in the chosen diagram language. For example, a flowchart in Mermaid starts from a graph or flowchart declaration, while a PlantUML sequence diagram starts from @startuml. The exact keywords depend on the type you selected, so check the examples or cheat sheet for the type you are using.

3. Render and preview

Submit the description so Kroki renders it. The result is the diagram image produced from your text. If the output does not look right, the problem is almost always in the source text — a missing declaration, a typo in a node name, or unsupported syntax — so edit the description and render again.

4. Copy the image or link

Once the diagram renders correctly, copy the generated image or its link so you can embed it in documentation, a README, a wiki, or a ticket. Because the diagram is defined by text, you can keep the source alongside the image and re-render it whenever the description changes.

A concrete example

Suppose you need a simple flow for a support process. You would:

  1. Choose a flowchart-capable type such as Mermaid.
  2. Write a description that starts the flow, adds each step as a node, and connects the nodes in order.
  3. Render it and check that the arrows point the way you intended.
  4. Copy the image or link into your documentation.

If a node label contains characters that the syntax treats specially, quote or escape them, then render again.

Common snags

  • Wrong syntax for the type. Each diagram type has its own grammar. A description that works in one type will not necessarily work in another.
  • Missing start/end markers. Many textual diagram languages require explicit opening and closing lines. Omitting them usually produces an error or an empty render.
  • Assuming a local install is required. The hosted site is enough for a one-off diagram; using Kroki from your own pipeline is a separate setup decision.
  • Expecting a visual editor. Kroki is text-first. You edit the description, not the shapes.

When this approach fits

Use Kroki when you want diagrams that live as text you can version, review, and regenerate, and when you are comfortable writing the source syntax for the diagram type you need. If you need to draw freely by hand or adjust individual shapes interactively, a graphical editor will be a better fit.