A few weeks back, I wrote an article about how you can add Mermaid diagrams to your Markdown document. In this document, I will extend that technology and explain how you can add

BlockDiag  BPMN️  Bytefield️  SeqDiag  ActDiag  NwDiag  PacketDiag  RackDiag
C4 with PlantUML  D2  DBML  Ditaa  Erd Excalidraw️  GraphViz  Mermaid  Nomnoml
Pikchr️  PlantUML  Structurizr  Svgbob  TikZ  UMlet  Vega  Vega-Lite  WaveDrom
WireViz

To your markdown, Asciidoc, or any other document.

1. Problem Statement

The problem statement is the same as in the previous article. You want diagrams in your document, but the formatting tool does not support the diagramming tool you want to use. It is an architectural problem that cannot be solved until we combine the different responsibilities: formatting and information content management.

2. Approach to Solve the problem

The approach is the same again; I am talking about the same tool.

The basic idea is, again: the separation of concerns. The document markup language should be responsible for the document structure and content. The diagramming tool should be responsible for the diagramming. The meta markup should be responsible for the integration of the two. I will not repeat here all the arguments why this is a good idea.

3. Suggested Solution, Tools

The suggested solution is to use Jamal as the meta markup. However, this time we will not use Mermaid as a diagramming tool locally. Instead, we will enjoy the services of the diagramming tool Kroki.

3.1. What is Kroki

Kroki is a simple tool, and it is as genial as simple as the idea is. It is nothing else than a web service implementing one GET endpoint to execute 27 different diagramming tools. If you

  1. create your diagram text

  2. convert the text to base64 encoded

  3. open the URL https://kroki.io/<tool>/<format>/<base64 encoded text>

then you will get the diagram in the format you requested.

Brilliant.

If you develop something for open source, you can use Kroki for free. If you develop something secret, afraid that your secret gets out to the internet, you can start Kroki on-premise. Kroki is available as a docker image and also in other modes. I recommend Docker if you do not trust the public service.

Why do we need Jamal?

Well, what happens if the service is temporarily not available? Why should you pull the image all the time from the internet?

3.2. Need for Jamal

After the first few iterations of editing the diagram file, converting it to base64, and opening the URL, you will realize that it is simple but repetitive work. Precisely the type of work that should be automatized. And that is what Jamal is for.

The next release of Jamal 2.3.0 will come with a new macro, including a file that you can import as

{@import res:kroki.jim}

It defines a macro kroki that you can use to include the diagram in your document.

The beauty of this solution is that the implementation did not need any Kroki-specific Java code. It was all already there. The macros used in that file are available from github:

{@comment }
define the macro kroki to download the image from kroki.io and reference it either Asciidoc or Markdown syntax

{@define [tail] kroki($name,$dt,$ft,$x)={#if /{#string:equals/md.jam/{#file (format="$extension2") {@pos (top format=%f)}}}/![]({kroki:download |$name|$dt|$ft|$x})/image::{kroki:download |$name|$dt|$ft|$x}[]}}

{@define kroki:download($name,$dt,$ft,$x)={#define URL={kroki:url|$dt|$ft|$x}}\
{#memoize (file="$name.$ft" hashFile="$name.$ft.hash" hashCode="{#hashCode {URL}}")
{@ident {#download (file="$name.$ft") {URL}}}}$name.$ft}

{@define kroki:url($dt,$ft,$x)=https://kroki.io/$dt/$ft/{@base64 (compress url)$x}}

The macros check whether the included file is md.jam (Markdown) or not; based on that, it generates a Markdown image reference or Asciidoc. It also checks if the diagram has been downloaded and changed since the last time it was edited. It downloads the diagram only if it has changed since the last time it was generated. To do that, it uses the general purpose memoize, download, file, and hashCode macros.

This tooling also allows you to use variables in the diagram text. Whether the diagram supports arithmetical, macro, or string operations does not matter. Jamal provides it before the diagram text is sent to Kroki.

If you want to see some excellent examples, please visit the sample pages.

Use the URL without the .jam at the end to see the GitHub-rendered versions.

4. Summary and Takeaway

This article discussed integrating 27 diagram types into your Asciidoc, Markdown, or any other markup document. There is no excuse anymore for any outdated diagram.

Comments

Please leave your comments using Disqus, or just press one of the happy faces. If for any reason you do not want to leave a comment here, you can still create a Github ticket.