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

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):

1. $XDG_CACHE_HOME/kroki (if XDG_CACHE_HOME is set)
2. ~/.cache/kroki (if HOME is set)
3. System temp directory + /kroki (final fallback)
4. 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.

In PlantUML sequence diagrams, line.stroke and background.fill also style the participant lifelines (LifeLineBorderColor/LifeLineBackgroundColor), so lifelines stay visible instead of falling back to PlantUML's built-in default — which matters most when using styles_dark.

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

*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

See Also

Diagram examples can be found here.

More information about installing a self-manged Kroki-Service here.

More Plugins for MkDocs can be found here

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 git@github.com: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:

1. Validate the version format (semantic versioning: X.Y.Z)
2. Check that the working tree is clean
3. Update the __version__ in kroki/__init__.py
4. Create a commit: chore: Bump version to X.Y.Z
5. Create an annotated git tag: vX.Y.Z
6. Push the commit and tag to GitHub
7. 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)