Pelican and Kroki

This week I learned to love diagraming using textual descriptions of the diagrams.

The benefits are obvious:

  • Automatic layout
  • Versioning and diffing using git
  • LLM friendly

Lets start and see what you will be able to do when you are finished reading this arcticle (given you follow all the instructions).

By inserting this code into your sites markdown: (remove the space after the first backtick)

` ``<your diagram type e.g. mermaid>
graph TD
    a[Write Text] --> b[Pelican]
    b --> c[Render Markdown]
    b --> c1[Do something in parallel]
    c --> e[Encounter Fences]
    e --> f[Render Diagram]
    c1 --> g[Output HTML]
    f --> g
` ``

You will get this fancy diagram rendered inside your websites code.

If you prefer to have your code a little bit more structured and want your diagrams in separate files you can also do this. Put your diagram code into a file e.g. kroki.excalidraw and use it include its content inside a matching ```excalidraw block

The result could look like this.

Bonus: You can also simply copy from Excalidraw and paste the json into a file this way. Do the opposite whenever you want to continue working on your diagram.

Unfortunately all of this is not an out of the box feature of pelican, but instead needs some setup to make it work. In the following line I will briefly describe how my setup looks like.

Kroki installation

I have installed kroki plus the optional extensions for mermaid, bpmn, execlidraw and diagrams.net using podman and podman-compose

You can do exactly the same thing using docker and docker-compose. There should not be any major differences. The installation on alpine went smoothly.

What I did was:

  • Install podman and podman-compose using apk add podman podman-compose iptables
  • Configure cgroups for running containers as non root user (refer to Alpine Wiki)
  • Create a new directory called kroki next to the content directory of my pelican project
  • Create a file called docker-compose.yml inside the kroki directory
  • Use the content of the docker-compose.yml at https://github.com/yuzutech/kroki as a base
  • Remove the expose sections for all containers since I dont want to expose the ports to the outside world
  • Run podman compose up -d from inside the kroki directory

Link Pelican to Kroki

Add the following configuration to the pelicanconf.py

MARKDOWN = {
    'extension_configs': {
        'markdown_kroki': {
            'kroki_url': 'http://localhost:8000',
            'img_src': 'data'
        },
    },
}

Note: I had to adjust the img_src property. The default value of link which if found in the markdown-kroki documentation was not working.

Instead of inserting a link into my page, which points to my kroki server (which will never works, since it is not publicly exposed), the image will instead be inserted as a base64 encoded data-url into the pages html.

Additionally I have adjusted the port to 8000 which itself is matching the port in port property of the core container in our docker-compose.yml

Room for improvement

Image loading / performance

Currently the images are inserted into the html file of the page itself. I could imagine that this does not scale very well.

For pages with a lot of diagrams the html file would become very large and therefore slow to load. Instead it would make sense to generate the images during site generation in pelican and publish them as static resources through the webserver.

After two minutes of googling I could not find an out of the box solution for my problem.

Maybe there is some image post processing plugin avaiable. In the end, we only want to add an additional processing step of internalizing the external kroki images.

The performance gains are obvious. Images can be cached and loaded asynchronously.

Viewer for Diagrams

For larger diagrams the screen is to small to fit the whole diagram into the screen and still being able to read all the captions and texts. Therefor some interactive viewer with zoom and pan features, would be helpful as a wrapper.

social