# Kroki — Unified API for Generating Diagrams from Text

> A free, open-source service that generates diagrams from textual descriptions. Kroki supports over 25 diagram types including Mermaid, PlantUML, D2, GraphViz, BPMN, Excalidraw, and more through a single HTTP API.

## Install

Save in your project root:

# Kroki — Unified API for Generating Diagrams from Text

## Quick Use
```bash
# Self-host with Docker
docker run -d -p 8000:8000 yuzutech/kroki

# Generate an SVG diagram via HTTP
curl -X POST https://kroki.io/mermaid/svg 
  --data-raw "graph TD; A-->B; B-->C;"
```

## 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/

---
Source: https://tokrepo.com/en/workflows/asset-a82f2a10
Author: AI Open Source