Diagram Support with Kroki

This guide explains how to use Kroki for text-based diagram rendering in Antora documentation sites.

The Problem

Documentation often requires diagrams to explain architecture, workflows, processes, and data models. Traditionally, teams face several challenges:

  1. Tool Fragmentation - Different diagram types require different tools (PlantUML for UML, Mermaid for flowcharts, Graphviz for graphs, etc.)

  2. Binary Files - Image-based diagrams (PNG, JPG) are binary files that don’t work well with version control (no diffs, merge conflicts)

  3. Maintenance Burden - Updating diagrams requires opening specialized tools, exporting to image formats, committing both source and image files, and keeping them in sync

  4. Collaboration Issues - Not all team members have the same diagram tools installed

  5. Documentation Drift - Diagrams become outdated because updating them is cumbersome

The Solution: Kroki

Kroki provides unified diagram rendering for 20+ formats through a single service.

How It Works

During the Antora build process:

  1. Kroki extension detects diagram blocks in your AsciiDoc files

  2. Sends the diagram source to the Kroki service

  3. Receives rendered SVG/PNG images

  4. Embeds them in the generated HTML documentation

Supported Diagram Types

Format Use Case Example

PlantUML

UML diagrams, sequence diagrams, component diagrams

Architecture, API flows

C4

Architecture diagrams (Context, Container, Component, Code)

System architecture

BPMN

Business process diagrams

Workflow documentation

Mermaid

Flowcharts, sequence diagrams, Gantt charts

Process flows

GraphViz

Graph visualizations

Dependency graphs

Ditaa

ASCII art diagrams

Simple sketches

BlockDiag

Block diagrams

Infrastructure diagrams

SeqDiag

Sequence diagrams

Interaction flows

ActDiag

Activity diagrams

User journeys

Nwdiag

Network diagrams

Network topology

ERD

Entity-relationship diagrams

Database schemas

Excalidraw

Hand-drawn style diagrams

Informal diagrams

Vega/Vega-Lite

Data visualizations

Charts and graphs

Using the VSHN Antora Image

Why VSHN?

The official antora/antora:latest Docker image is minimal and doesn’t include diagram rendering extensions. The VSHN extended Antora image (ghcr.io/vshn/antora) includes:

  • Kroki Pre-installed - asciidoctor-kroki extension ready to use

  • Additional Tools - antora-site-generator-lunr (search), make, git, yq, jq

  • Drop-in Replacement - Same CLI interface as official Antora image

  • Version Pinning - Explicit version tags for reproducible builds

  • Community Maintained - Actively maintained by VSHN

Decision Matrix

Criteria Official + Custom VSHN Image

Diagram Support

Need to add

Pre-installed

Maintenance Effort

High (custom builds)

Low (community maintained)

Additional Features

None

Search, tools

Time to Deploy

Requires build pipeline

Immediate

Registry Setup

Required

Public registry (ghcr.io)

Configuration

Kubernetes Deployment

- name: antora-build
  image: ghcr.io/vshn/antora:3.1.4

Antora Playbook

asciidoc:
  extensions:
    - asciidoctor-kroki
  attributes:
    kroki-fetch-diagram: true

Local Development (package.json)

"devDependencies": {
  "@antora/cli": "^3.1.2",
  "@antora/site-generator-default": "^3.1.2",
  "asciidoctor-kroki": "^0.18.1"
}

Usage Examples

PlantUML Sequence Diagram

[plantuml,format=svg]
----
@startuml
actor User
participant "API Gateway" as API
participant "Auth Service" as Auth
database "User DB" as DB

User -> API: POST /login
API -> Auth: Validate credentials
Auth -> DB: Query user
DB --> Auth: User data
Auth --> API: JWT token
API --> User: 200 OK + token
@enduml
----

C4 Architecture Diagram

[plantuml,format=svg]
----
@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

Person(user, "User", "Documentation reader")
System_Boundary(docs, "Documentation System") {
    Container(nginx, "NGINX", "Web Server", "Serves static content")
    Container(antora, "Antora", "Generator", "Builds documentation")
}
System_Ext(git, "Git Repository", "Source content")
System_Ext(kroki, "Kroki", "Diagram renderer")

Rel(user, nginx, "Views", "HTTPS")
Rel(antora, git, "Clones", "Git")
Rel(antora, kroki, "Renders diagrams", "HTTPS")
Rel(antora, nginx, "Generates content")
@enduml
----

Block Diagram

[blockdiag]
----
blockdiag {
  A [label = "Init Container"];
  B [label = "Git Clone"];
  C [label = "Antora Build"];
  D [label = "NGINX Serve"];

  A -> B -> C -> D;
}
----

Benefits

For Documentation Authors

  • Version Control Friendly - Diagrams are text, get proper diffs

  • No Special Tools - Just a text editor

  • Fast Updates - Change text, commit, done

  • Consistency - Diagrams follow same style automatically

  • Collaboration - Easy to review and suggest changes

For Teams

  • Single Source of Truth - Diagram source lives with documentation

  • Automated Rendering - No manual export/import steps

  • Always Up-to-Date - Diagrams rebuild with every deployment

  • Multiple Formats - Choose the right diagram type for the job

  • Professional Output - High-quality SVG diagrams

For Operations

  • Zero Maintenance - Kroki service handles all rendering

  • Stateless - No local diagram rendering dependencies

  • Scalable - Kroki handles concurrent requests

  • Reliable - Diagrams cached during build

Security Considerations

Public Kroki Service

By default, diagrams are rendered using the public Kroki service at https://kroki.io

Privacy implications:

  • Diagram source code is sent to external service

  • Consider if your diagrams contain sensitive information

  • Public service has rate limits

Self-Hosted Kroki

If you need to keep diagram source private, deploy your own Kroki instance:

# antora-playbook.yml
asciidoc:
  attributes:
    kroki-server-url: https://kroki.your-company.com

See Kroki Installation Guide for setup instructions.

Performance

Build Time Impact

  • Minimal Impact - ~1-2 seconds per diagram

  • Concurrent Rendering - Multiple diagrams rendered in parallel

  • Caching - Rendered diagrams cached in Antora cache directory

Site Size

  • SVG Format - Vector graphics, small file size

  • PNG Alternative - Available with format=png

  • No Runtime Overhead - Diagrams rendered at build time, not on page load

Troubleshooting

Diagram Not Rendering

Check 1: Verify extension is enabled

grep -A5 "asciidoc:" antora-playbook.yml

Check 2: Check build logs for errors

Check 3: Test diagram syntax at https://kroki.io

Common Syntax Errors

// Wrong - missing format specification
[plantuml]

// Correct
[plantuml,format=svg]

@startuml …​ @enduml











Network Issues




If Kroki service is unreachable during build:






    

  • 

    Check network connectivity from build environment
    

    • 

  • 

    Verify firewall rules allow HTTPS to kroki.io
    

    • 

  • 

    Consider self-hosted Kroki instance
    

    • 













References