A Jekyll plugin to convert diagram descriptions into images using Kroki.
Add the jekyll-kroki Gem to the :jekyll_plugins group of your site's Gemfile:
group :jekyll_plugins do
gem "jekyll-kroki"
endKroki 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 encodes the diagram descriptions, renders them as SVG images using the Kroki server, then embeds them in the generated HTML:
Since the images are rendered and embedded at build-time, the Jekyll site remains completely static and doesn't depend on access to the Kroki server later on. This also eliminates all of the client-side processing that is typically used to render diagrams into images.
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.
Self-managed or dedicated GitLab instances can additionally enable the Kroki integration, which adds support for all the 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.
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 can bypass these setup steps and will thus build faster. jekyll-kroki is built with performance in mind to minimise the build time of even the largest sites with thousands of diagrams.
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 can choose to operate their own Kroki instance to ensure consistency and use compute resources efficiently. For individuals, you can also opt to run Kroki locally.
You can specify the following parameters in the Jekyll _config.yml file:
| Parameter | Default value | Description |
|---|---|---|
url |
https://kroki.io |
The URL of the Kroki instance to use |
http_retries |
3 |
The number of HTTP retries |
http_timeout |
15 |
The HTTP timeout value in seconds |
max_concurrent_docs |
8 |
The maximum number of Jekyll documents to render concurrently |
For example:
kroki:
url: "https://my-kroki.server"
http_retries: 3
http_timeout: 15
max_concurrent_docs: 8Embedding untrusted SVGs directly in HTML files can introduce security risks. Use a Kroki instance that you trust, or consider hosting your own local/private instance. For added security, you can configure a Content Security Policy (CSP) by adding custom Webrick headers in your Jekyll _config.yml file:
webrick:
headers:
Content-Security-Policy: "Add a policy here"Bug reports and pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.