mkdocs-kroki-plugin 1.6.0

MkDocs plugin for Kroki-Diagrams

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

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.

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

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 [e-mail]: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)