About mkdocs-kroki-plugin

# mkdocs-kroki-plugin [![PyPI version](https://badge.fury.io/py/mkdocs-kroki-plugin.svg)](https://badge.fury.io/py/mkdocs-kroki-plugin) [![PyPI - Downloads](https://img.shields.io/pypi/dm/mkdocs-kroki-plugin)](https://pypi.org/project/mkdocs-kroki-plugin/) [![Test Status](https://github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin/actions/workflows/test.yml/badge.svg)](https://github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin/actions/workflows/test.yml) [![Lint Status](https://github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin/actions/workflows/lint.yml/badge.svg)](https://github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin/actions/workflows/lint.yml) [![Python versions](https://img.shields.io/pypi/pyversions/mkdocs-kroki-plugin.svg)](https://pypi.org/project/mkdocs-kroki-plugin/) This is a MkDocs plugin to embed Kroki-Diagrams into your documentation. ## Setup Install the plugin using pip: `pip install mkdocs-kroki-plugin` Activate the plugin in `mkdocs.yml`: ```yaml plugins: ... - kr ...

a

Published by

avateam-it-systemhaus

Visit View Profile

README.md

View on GitHub

mkdocs-kroki-plugin

This is a MkDocs plugin to embed Kroki-Diagrams into your documentation.

Setup

Install the plugin using pip:

pip install mkdocs-kroki-plugin

Activate the plugin in mkdocs.yml:

plugins:
    ...
      - kroki:

Config

Key	Description	Default
`server_url`	URL of your kroki-Server	`!ENV [KROKI_SERVER_URL, 'https://kroki.io']`
`fence_prefix`	Diagram prefix, set to an empty string to render all diagrams using Kroki	`kroki-`
`enable_block_diag`	Enable BlockDiag (and the related Diagrams)	`true`
`enable_bpmn`	Enable BPMN	`true`
`enable_excalidraw`	Enable Excalidraw	`true`
`enable_mermaid`	Enable Mermaid	`true`
`enable_diagramsnet`	Enable diagrams.net (draw.io)	`false`
`http_method`	Http method to use (`GET` or `POST`) Note: On `POST` the retrieved images are stored next to the including page in the build directory	`GET`
`request_timeout`	Timeout for HTTP requests in seconds. Increase this value if you encounter timeouts with large diagrams or overloaded kroki server instances.	`30`
`user_agent`	User agent for requests to the kroki server	`kroki.plugin/<version>`
`file_types`	File types you want to use Note: not all file formats work with all diagram types https://kroki.io/#support	`[svg]`
`file_type_overrides`	Overrides for specific diagram types to set the desired file type	`[]`
`tag_format`	How the image will be included in the resulting HTML (`img`, `object`, `svg`)	`img`
`fail_fast`	Errors are raised as plugin errors	`false`
`cache_dir`	Custom directory for caching rendered diagrams By default uses `$XDG_CACHE_HOME/kroki`, `~/.cache/kroki`, or temp directory	(automatic)
`diagram_background_color_light`	Background color for diagrams in light mode (CSS color value)	(none)
`diagram_background_color_dark`	Background color for diagrams in dark mode (CSS color value)	(none)
`styles`	Global style map for diagram elements (`box`, `actor`, `note`, `package`, `text`, `line`, `background`). See Global Styles.	(none)
`styles_light`	Style map applied in light mode. Use together with `styles_dark` for theme-aware diagrams. See Theme-Aware Styles.	(none)
`styles_dark`	Style map applied in dark mode. Use together with `styles_light` for theme-aware diagrams. See Theme-Aware Styles.	(none)

Example:

  - kroki:
      server_url: !ENV [ KROKI_SERVER_URL, 'https://kroki.io' ]
      file_types:
        - png
        - svg
      file_type_overrides:
        mermaid: png
      fail_fast: !ENV CI

Caching

The plugin automatically caches rendered diagrams to improve build performance, especially useful during mkdocs serve when diagrams would otherwise be re-rendered on every file save.

Note: Caching only applies when using http_method: POST. The GET method generates URLs pointing to the Kroki server and doesn't download diagram content.

How it works:

Diagrams are cached based on their content, type, format, and options
Unchanged diagrams are retrieved from cache instead of being re-rendered
Both in-memory and file-based caching are used for optimal performance
LRU strategy: Frequently accessed diagrams stay in cache, unused ones expire after 3 days
Cache cleanup runs automatically on plugin initialization with minimal overhead

Cache location (fallback hierarchy):

$XDG_CACHE_HOME/kroki (if XDG_CACHE_HOME is set)
~/.cache/kroki (if HOME is set)
System temp directory + /kroki (final fallback)
Custom location: Set cache_dir in plugin configuration to override

Example with custom cache directory:

  - kroki:
      cache_dir: .cache/kroki  # Store cache in project directory

Usage

Use code-fences with a tag of kroki-<Module> to replace the code with the wanted diagram.

Diagram options can be set as well.

Example for BlockDiag:

```kroki-blockdiag no-transparency=false
blockdiag {
  blockdiag -> generates -> "block-diagrams";
  blockdiag -> is -> "very easy!";

  blockdiag [color = "greenyellow"];
  "block-diagrams" [color = "pink"];
  "very easy!" [color = "orange"];
}
```

You can render diagram from file with @from_file: directive:

```kroki-bpmn
@from_file:path/to/diagram.bpmn
```

Display Options

You can control the display size and alignment of diagrams using display-width, display-height, and display-align options. These options set inline CSS styles on the rendered element.

Size Options

```kroki-plantuml {display-width=500px}
@startuml
Alice -> Bob: Hello
Bob --> Alice: Hi!
@enduml
```

You can use both width and height together:

```kroki-blockdiag {display-width=400px display-height=200px}
blockdiag {
  A -> B -> C;
}
```

Alignment

Use display-align to position diagrams horizontally. Valid values are left, center, and right.

```kroki-mermaid {display-width=300px display-align=center}
graph LR
    A[Start] --> B[End]
```

This sets display: block and appropriate margin values:

center: margin-left: auto; margin-right: auto
right: margin-left: auto; margin-right: 0
left: margin-left: 0; margin-right: auto

Notes:

Display options are handled by the plugin and are not sent to the Kroki server
Setting only display-width or display-height allows the browser to scale proportionally
These options work with all tag_format settings (img, object, svg)
Size values can be any valid CSS value (e.g., 500px, 50%, auto, 20em)

Background Color

You can set a background color for diagrams that adapts to light/dark themes. This is useful when diagrams have transparent backgrounds that don't display well in certain color schemes.

Global Configuration

Set default background colors for all diagrams in mkdocs.yml:

plugins:
  - kroki:
      diagram_background_color_light: white
      diagram_background_color_dark: "#333"

Per-Diagram Override

Override the global settings for individual diagrams using bg-light and bg-dark:

```kroki-plantuml {bg-light=#f5f5f5 bg-dark=#1a1a1a}
@startuml
Alice -> Bob: Hello
@enduml
```

How It Works

When both light and dark colors are set, the plugin uses the CSS light-dark() function:
```
background: light-dark(white, #333);
```
When only one color is set, it applies as a simple background:
```
background: white;
```
When neither is set, no background style is applied

Notes:

The light-dark() CSS function requires the page to have color-scheme: light dark set. MkDocs themes like Material for MkDocs handle this automatically.
Per-diagram options (bg-light, bg-dark) override global settings
You can set only one color per-diagram while inheriting the other from global config
Works with all tag_format settings (img, object, svg)

Global Styles

Apply a consistent color scheme across all supported diagram types with the styles config. Define generic element styles once, and the plugin translates them into diagram-type-specific directives before rendering.

plugins:
  - kroki:
      styles:
        box:
          fill: "#e6f3ff"
          stroke: "#0066cc"
        actor:
          fill: "#ffe0b2"
          stroke: "#bf360c"
        note:
          fill: "#ffffcc"
          stroke: "#999900"
          color: "#666600"
        package:
          fill: "#fff3e0"
          stroke: "#e65100"
          color: "#bf360c"
        text:
          fill: "#333333"
          font-family: "Arial"
          font-size: "14"
        line:
          stroke: "#666"
          font-color: "#ff0000"
          font-family: "Arial"
          label-background: "#ffffff"
        background:
          fill: "#fff"

The actor element styles persons and actors separately from boxes. When actor is not configured, person elements fall back to box styles in diagram types that support it (C4 PlantUML).

The note element styles note boxes (fill, stroke, and text color) in diagram types that support them (PlantUML, C4 PlantUML, Mermaid). The package element styles package containers independently from regular boxes (PlantUML, C4 PlantUML); since box already sets PackageBackgroundColor/PackageBorderColor, package overrides those defaults.

To skip style injection on a specific code block, use no-style-inject=true:

```kroki-mermaid no-style-inject=true
graph LR
    A[Unstyled] --> B[Diagram]
```

Support Matrix

Style	PlantUML	C4 PlantUML	Mermaid	GraphViz	BlockDiag*	Nomnoml	D2	Structurizr
`box.fill`	✅	✅	✅	✅	✅	✅	✅	✅
`box.stroke`	✅	✅	✅	✅	❌	✅	✅	✅
`actor.fill`	✅	✅	✅	❌	❌	❌	❌	✅
`actor.stroke`	✅	✅	✅	❌	❌	❌	❌	✅
`note.fill`	✅	✅	✅	❌	❌	❌	❌	❌
`note.stroke`	✅	✅	✅	❌	❌	❌	❌	❌
`note.color`	✅	✅	✅	❌	❌	❌	❌	❌
`package.fill`	✅	✅	❌	❌	❌	❌	❌	❌
`package.stroke`	✅	✅	❌	❌	❌	❌	❌	❌
`package.color`	✅	✅	❌	❌	❌	❌	❌	❌
`text.fill`	✅	✅	✅	✅	✅	❌	✅	✅
`text.font-family`	✅	✅	❌	✅	❌	✅	❌	❌
`text.font-size`	✅	✅	❌	❌	✅	✅	✅	✅
`line.stroke`	✅	✅	✅	✅	✅	❌	✅	✅
`line.font-color`	❌	❌	❌	✅	❌	❌	✅	❌
`line.font-family`	❌	❌	❌	✅	❌	❌	❌	❌
`line.label-background`	❌	❌	✅	❌	❌	❌	❌	❌
`background.fill`	✅	✅	✅	✅	❌	✅	✅	❌

*BlockDiag includes: blockdiag, seqdiag, actdiag, nwdiag, packetdiag, rackdiag.

Diagram types not listed (BPMN, ByteField, DBML, Ditaa, ERD, Excalidraw, Pikchr, SVGBob, Symbolator, TikZ, UMlet, Vega, VegaLite, WaveDrom, WireViz, diagrams.net) do not support source-level style injection.

Theme-Aware Styles

When you need different diagram colors for light and dark mode — not just a different background, but different fills, strokes, and text colors baked into the diagram itself — use styles_light and styles_dark together.

plugins:
  - kroki:
      styles_light:
        box:
          fill: "#e8f4fd"
          stroke: "#0066cc"
        text:
          fill: "#24292e"
        background:
          fill: "#ffffff"
      styles_dark:
        box:
          fill: "#1a2a3a"
          stroke: "#4da6ff"
        text:
          fill: "#e0e0e0"
        background:
          fill: "#1e1e1e"

The plugin renders two versions of each diagram — one with light styles, one with dark — and emits two <img> tags using MkDocs Material's light/dark image feature:

<img alt="Kroki" src="diagram-light.svg#only-light" />
<img alt="Kroki" src="diagram-dark.svg#only-dark" />

Material's CSS then shows the correct image based on the active color scheme.

Notes:

Requires MkDocs Material theme — the #only-light/#only-dark mechanism is Material-specific
Requires tag_format: img (the default). object and svg formats fall back to light-mode styles only with a warning
Requires http_method: POST (images must be downloaded to use this feature)
styles_light/styles_dark take precedence over styles when set; using all three simultaneously logs a warning
The no-style-inject=true per-diagram option skips injection for both light and dark
Supports the same style properties and diagram types as the single styles config (see Support Matrix)
Backstage TechDocs: Backstage does not set Material's data-md-color-scheme attribute, so both light and dark images will be visible by default. Add a prefers-color-scheme CSS fallback to your extra stylesheets to fix this:
```
@media (prefers-color-scheme: light) {
    img[src$="#only-dark"] { display: none; }
}
@media (prefers-color-scheme: dark) {
    img[src$="#only-light"] { display: none; }
}
```

Contributors

Want to appear in the list of contributors?

Get started by reading the Contribution Guidelines

Pre-Release-Versions

Install the newest pre-release version using pip:

pip install -i https://test.pypi.org/simple/ mkdocs-kroki-plugin

Development

Setup

git clone [email protected]:AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin.git
cd mkdocs-kroki-plugin
uv sync

Pre-commit Hooks

Install the pre-commit hooks to run linting, type checking, and tests automatically on commit:

uv run pre-commit install

To run all hooks manually:

uv run pre-commit run --all-files

Testing

Run tests:

uv run pytest

Run tests with coverage:

uv run pytest --cov

Linting & Formatting

Run ruff for linting and formatting:

uv run ruff check .
uv run ruff format .

Type Checking

Run mypy:

uv run --group types mypy kroki

Preview playground using mkdocs

uv run task playground:mkdocs

Preview playground using techdocs-cli

uv run task playground:techdocs

Creating a Release

Use the release script to create a new version:

./release.py <version>

For example:

./release.py 1.2.3

The script will:

Validate the version format (semantic versioning: X.Y.Z)
Check that the working tree is clean
Update the __version__ in kroki/__init__.py
Create a commit: chore: Bump version to X.Y.Z
Create an annotated git tag: vX.Y.Z
Push the commit and tag to GitHub
Open your browser to create a GitHub release where you can add the changelog

Requirements:

Clean working tree (no uncommitted changes)
Version must follow semantic versioning format (e.g., 1.2.3)

mkdocs-kroki-plugin

About mkdocs-kroki-plugin

Platforms

Languages

Links

README.md

mkdocs-kroki-plugin

Setup

Config

Caching

Usage

Display Options

Size Options

Alignment

Background Color

Global Configuration

Per-Diagram Override

How It Works

Global Styles

Support Matrix

Theme-Aware Styles

Contributors

See Also

Pre-Release-Versions

Development

Setup

Pre-commit Hooks

Testing

Linting & Formatting

Type Checking

Preview playground using mkdocs

Preview playground using techdocs-cli

Creating a Release