Kroki — Unified API for Diagrams as Code

Introduction

Kroki provides a single HTTP API to render over 20 diagram types from text. Instead of installing and configuring separate tools for PlantUML, Mermaid, GraphViz, BPMN, and others, you send text to Kroki and receive SVG, PNG, or PDF output.

What Kroki Does

• Renders diagrams from plain text for 20+ formats via a unified REST API
• Supports GraphViz (DOT), PlantUML, Mermaid, C4, BPMN, UML, ERD, Vega, Ditaa, and more
• Returns output as SVG, PNG, PDF, or base64-encoded images
• Accepts diagram source via POST body or URL-encoded GET parameter
• Runs as a self-hosted Docker container or set of companion containers

Architecture Overview

Kroki is a gateway service written in Java (Vert.x) that routes diagram requests to specialized rendering backends. Each backend runs in its own container: yuzutech/kroki-mermaid, yuzutech/kroki-bpmn, yuzutech/kroki-excalidraw, etc. The gateway handles format detection, input encoding, and output content negotiation. For simpler setups, a single all-in-one image bundles the most popular backends.

Self-Hosting & Configuration

• Deploy with Docker Compose using the official docker-compose.yml for all backends
• Use the standalone image for a lighter setup with the most common diagram types
• Configure timeouts and max payload size via environment variables
• Place behind a reverse proxy (Nginx, Caddy) with caching for repeated diagram renders
• Integrate into CI/CD pipelines to generate documentation diagrams from code

Key Features

• One API endpoint for 20+ diagram languages, eliminating tool sprawl
• No client-side rendering dependencies; all processing happens server-side
• Stateless service that scales horizontally behind a load balancer
• Integrates with documentation tools like Asciidoctor, Sphinx, MkDocs, and Hugo
• Free and open source under the MIT license

Comparison with Similar Tools

• PlantUML Server — supports only PlantUML; Kroki unifies 20+ diagram types under one API
• Mermaid CLI — client-side rendering for Mermaid only; Kroki renders server-side for any format
• Draw.io — GUI-based diagramming; Kroki is text-based and version-control friendly
• Diagrams (Python) — Python code to cloud architecture diagrams; Kroki handles arbitrary diagram syntaxes
• GitHub/GitLab native rendering — limited to Mermaid; Kroki supports the full range of diagram languages

FAQ

Q: Which diagram types does Kroki support? A: GraphViz, PlantUML, Mermaid, C4 (via PlantUML), BPMN, Ditaa, Nomnoml, Svgbob, WaveDrom, Vega, Vega-Lite, Bytefield, BlockDiag, SeqDiag, ActDiag, NwDiag, PacketDiag, RackDiag, Pikchr, Structurizr, Excalidraw, D2, and UMlet.

Q: Can I use Kroki in my documentation pipeline? A: Yes. Plugins exist for Asciidoctor, Sphinx, Hugo, MkDocs, Docusaurus, and Confluence to embed diagram source in docs and render at build time.

Q: How does the GET endpoint work? A: Compress the diagram text with deflate, base64url-encode it, and append to the URL path. This allows embedding diagram URLs in Markdown images without a POST request.

Q: Is there a public instance I can use? A: Kroki.io provides a free public instance for testing. For production use, self-host to avoid rate limits and ensure availability.

Sources

• https://github.com/yuzutech/kroki
• https://kroki.io/