Kroki Reference

Kroki unified diagram rendering. Container lifecycle, AsciiDoc block syntax for D2/Mermaid/GraphViz/PlantUML, and troubleshooting.

What Kroki Does

Kroki provides a unified HTTP API to render diagrams from textual descriptions. In the Antora workflow, Kroki runs as a local container during build, converting diagram source blocks into SVG images.

Container Lifecycle

Start Kroki for local builds

podman run -d --name kroki -p 8000:8000 yuzutech/kroki
# Or with Docker:
docker run -d --name kroki -p 8000:8000 yuzutech/kroki

The Makefile handles this automatically

make          # Starts Kroki, builds, stops Kroki
make serve    # Starts Kroki, builds, stops Kroki, serves

Manual stop

podman stop kroki && podman rm kroki

AsciiDoc Integration

D2 diagram block

[d2,target=my-diagram,format=svg]
....
server -> database: queries
server -> cache: lookups
....

Mermaid diagram block

[mermaid,target=flow-diagram,format=svg]
....
graph LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]
....

GraphViz (dot) diagram block

[graphviz,target=graph,format=svg]
....
digraph {
    rankdir=LR
    A -> B -> C
}
....

PlantUML diagram block

[plantuml,target=sequence,format=svg]
....
@startuml
Client -> Server: Request
Server -> Database: Query
Database --> Server: Result
Server --> Client: Response
@enduml
....

Supported Diagram Types

Type Block Identifier

Type	Block Identifier
D2	`[d2,target=name,format=svg]`
Mermaid	`[mermaid,target=name,format=svg]`
GraphViz	`[graphviz,target=name,format=svg]`
PlantUML	`[plantuml,target=name,format=svg]`
Ditaa	`[ditaa,target=name,format=svg]`
Structurizr	`[structurizr,target=name,format=svg]`
BPMN	`[bpmn,target=name,format=svg]`
Bytefield	`[bytefield,target=name,format=svg]`

[d2,target=name,format=svg]

Mermaid

[mermaid,target=name,format=svg]

GraphViz

[graphviz,target=name,format=svg]

PlantUML

[plantuml,target=name,format=svg]

Ditaa

[ditaa,target=name,format=svg]

Structurizr

[structurizr,target=name,format=svg]

BPMN

[bpmn,target=name,format=svg]

Bytefield

[bytefield,target=name,format=svg]

Antora Playbook Configuration

Enable Kroki in antora-playbook.yml

asciidoc:
  extensions:
    - asciidoctor-kroki
  attributes:
    kroki-server-url: http://localhost:8000
    kroki-fetch-diagram: true

kroki-fetch-diagram: true downloads rendered images during build, embedding them in the output. Without it, diagrams are fetched at page load time.

Output Formats

SVG (default, recommended)

[d2,target=diagram,format=svg]

PNG (raster, larger file size)

[d2,target=diagram,format=png]

SVG is preferred: scalable, searchable text, smaller files.

Troubleshooting

Kroki not running — diagrams render as broken images

podman ps | grep kroki
# If empty, start it:
podman run -d --name kroki -p 8000:8000 yuzutech/kroki

Test Kroki endpoint directly

curl -s http://localhost:8000/d2/svg \
  -H "Content-Type: text/plain" \
  -d 'a -> b' | head -5
# Should return SVG XML

Diagram syntax error — check Kroki logs

podman logs kroki 2>&1 | tail -20