jekyll-kroki

A Jekyll plugin to convert diagram descriptions into images using Kroki.

Installation

Add the jekyll-kroki Gem to the :jekyll_plugins group of your site's Gemfile:

group :jekyll_plugins do
  gem "jekyll-kroki"
end

Usage

Kroki supports over 25 popular diagram scripting languages, including Blockdiag, D2, GraphViz, Mermaid, and PlantUML. The examples page and complete list of supported diagram languages provide a taste of what's possible.

In Markdown, simply write your diagram descriptions inside a fenced code block with the language specified:

```plantuml
participant Jekyll
participant Kroki #MediumSpringGreen

Jekyll -> Kroki: Encoded diagram description
Kroki --> Jekyll: Rendered diagram in SVG format
```

When Jekyll builds your site, the jekyll-kroki plugin will encode the diagrams, send them to the Kroki server for rendering, then replace the diagram descriptions in the generated HTML with the rendered images in SVG format:

The site remains truly static as the images are directly embedded in the HTML files served by Jekyll. Jekyll only depends on the Kroki server (which can also be run locally) during the build stage, and all of the client-side processing that is normally used to render diagrams into images is eliminated.

Advantages

Consistent syntax

Instead of using Liquid tags, jekyll-kroki leverages the same Markdown fenced code block syntax used by both GitLab and GitHub to display diagrams. Besides being more consistent, this means that diagram descriptions in Markdown files can be displayed consistently as images across the GitLab/GitHub UI and on GitLab/GitHub Pages sites generated using Jekyll. GitLab currently supports Mermaid and PlantUML, while GitHub only supports Mermaid.

Seamless GitLab integration

Self-managed GitLab instances can additionally enable the Kroki integration, which adds support for all the same diagram scripting languages used by jekyll-kroki. Furthermore, by pointing both GitLab and jekyll-kroki to the same Kroki instance, you can guarantee that diagrams are generated using identical versions of the diagram libraries.

Speed

The server-side nature of Kroki means that you don't have to deal with installing or updating any diagram library dependencies on your machine. Jekyll sites that are generated in CI/CD pipelines will thus build faster.

Flexibility

Kroki is available either as a free service or self-hosted using Docker. Organisations that frequently build large Jekyll sites with many diagrams or want maximum control over their data have the option of running their own Kroki instance to provide consistency and use compute resources efficiently.

Configuration

You can specify the URL of the Kroki instance to use in the Jekyll _config.yml file:

kroki:
  url: "https://my-kroki.server"

This is useful if you want to run a Kroki instance locally or your organisation maintains its own private Kroki server. The public Kroki instance https://kroki.io is used by default.

Security

Embedding diagrams as SVGs directly within HTML files can be dangerous. You should only use a Kroki instance that you trust (or run your own!). For additional security, you can configure a Content Security Policy (CSP) using custom Webrick headers in the Jekyll _config.yml file:

webrick:
  headers:
    Content-Security-Policy: "Add a policy here"

Contributing

Bug reports and pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.