Kroki is a wonderful tool I discovered during the time I worked as DevRel: it’s a small open source containerized application (compatible with OpenShift off-the-box) written in JavaScript, that encapsulates as many textual diagram formats as possible under a single unified API, offering a convenient way for users to generate diagrams, without needing to install separate libraries everywhere.
It supports an incredibly long list of formats; at the time of this writing the list includes: BlockDiag, BPMN, Bytefield, SeqDiag, ActDiag, NwDiag, PacketDiag, RackDiag, C4 with PlantUML, D2, DBML, Ditaa, Erd, Excalidraw, GraphViz, Mermaid, Nomnoml, Pikchr, PlantUML, Structurizr, Svgbob, Symbolator, TikZ, UMlet, Vega, Vega-Lite, WaveDrom, and WireViz.
The idea is that you can add to your documentation plain-text diagram representations, and then let Kroki render the diagram for you.
skinparam ranksep 20
skinparam dpi 125
skinparam packageTitleAlignment left
rectangle "Main" {
(main.view)
(singleton)
}
rectangle "Base" {
(base.component)
(component)
(model)
}
rectangle "<b>main.ts</b>" as main_ts
(component) ..> (base.component)
main_ts ==> (main.view)
(main.view) --> (component)
(main.view) ...> (singleton)
(singleton) ---> (model)
Then take the text above, embed it into a POST request to /plantuml/svg, and send it to the Kroki server; and this is what you would get back:
The Kroki documentation provides lots of information about how to install and use Kroki. There’s also a very useful examples page on the Kroki website, with many examples, and some of the images are simply crazy.
Regarding the editor experience, right before the pandemic I put together a short-lived Visual Studio Code extension for Kroki, but I never published it on the marketplace. Now there’s a new one, available on GitHub. It is worth noting that the official AsciiDoc extension for Visual Studio Code also supports Kroki directly.
Asciidoctor and Antora, two of my most beloved documentation tools ever, have support for Kroki thanks to the asciidoctor-kroki and the Diagrams extensions, so your diagrams can be stored directly inline with the source of your documentation text. Yes, directly into your Git repository, easy to track and understand, like this:
= Diagrams Extension Example with Kroki.io
The sequence diagram is below:
[plantuml]
....
@startuml
entity "Local or remote file" as file
box Browser #white
participant Browser as browser
participant "Asciidoctor\nBrowser Extension" as extension
box "Kroki Server" #white
participant "Kroki Gateway" as kroki
participant "Diagram generator" as generator
end box
file -> browser : AsciiDoc
browser -> extension : AsciiDoc
activate extension
extension -> kroki : encoded diagram text
kroki -> generator : diagram text
kroki <- generator : image
extension <- kroki : image
browser <- extension : HTML5
deactivate extension
@enduml
....
Using the proper extensions, Asciidoctor will send a request to Kroki, render your diagram, and insert the resulting image at this location in your document. It is recommended that you deploy your own copy of the Kroki container using the container on Podman, Docker, Kubernetes, or OpenShift, so that you can configure your server URL, and all your documentation diagrams will be rendered privately in your own instance, instead of the one in kroki.io.