Kroki — Unified API for Generating Diagrams from Text

Introduction

Kroki is an open-source service that provides a unified API for generating diagrams from textual descriptions. Instead of installing and configuring dozens of individual diagram tools, Kroki wraps them all behind a single HTTP endpoint that accepts text and returns SVG, PNG, or PDF output.

What Kroki Does

• Converts text-based diagram definitions into SVG, PNG, and PDF images
• Supports 25+ diagram formats through a single unified HTTP API
• Renders Mermaid, PlantUML, GraphViz, D2, BPMN, Excalidraw, and many more
• Provides a GET endpoint with encoded diagram data for embedding in Markdown
• Offers companion plugins for Asciidoctor, Sphinx, and other documentation tools

Architecture Overview

Kroki is a Java-based gateway service that routes diagram requests to the appropriate rendering backend. Each diagram type (PlantUML, Mermaid, GraphViz, etc.) runs as a separate container or embedded library. The gateway validates input, selects the correct backend, and returns the rendered output.

Self-Hosting & Configuration

• Deploy with Docker Compose using the official configuration that includes all backends
• Run a minimal setup with only the diagram types your team uses
• Configure behind a reverse proxy with caching for frequently rendered diagrams
• Set resource limits per backend to prevent denial-of-service from complex diagrams
• Use the free hosted instance at kroki.io for evaluation and small-scale use

Key Features

• One API for 25+ diagram languages eliminates per-tool installation
• Stateless HTTP API integrates easily into CI/CD, wikis, and documentation sites
• Encoded GET URLs allow diagram embedding in Markdown without a server roundtrip
• Output in SVG (default), PNG, or PDF to match any publishing requirement
• Active development adds new diagram types regularly

Comparison with Similar Tools

• Mermaid Live Editor — single diagram type; Kroki unifies 25+ types
• PlantUML Server — PlantUML only; Kroki includes PlantUML and many others
• Diagrams (Python) — code-first cloud architecture diagrams; Kroki is language-agnostic
• draw.io / Excalidraw — visual editors; Kroki renders from text for docs-as-code workflows
• D2 Playground — D2 only; Kroki supports D2 alongside other formats

FAQ

Q: Is the hosted kroki.io instance free? A: Yes. The public instance at kroki.io is free for reasonable use. For production workloads, self-host to avoid rate limits.

Q: Which diagram types are supported? A: Over 25 types including Mermaid, PlantUML, GraphViz (DOT), D2, BPMN, Excalidraw, Pikchr, Structurizr, Ditaa, BlockDiag, Vega, and WaveDrom.

Q: Can I add custom diagram types? A: Yes. Kroki's architecture allows adding new backends. Implement the rendering service and register it with the gateway.

Q: How do I embed diagrams in Markdown? A: Encode the diagram text in the URL path using Kroki's deflate+base64 encoding and reference the resulting URL as an image in Markdown.

Sources

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