Registry / web-framework / mkdocs-kroki-plugin

mkdocs-kroki-plugin

library1.6.0pypypi✓ verified 85d ago

mkdocs-kroki-plugin is an MkDocs plugin designed to embed Kroki-Diagrams directly into your documentation. It is currently at version 1.6.0 and maintains an active development cycle, releasing new features, bug fixes, and improvements frequently, as seen in its recent series of minor and patch releases.

web-framework

pip install mkdocs-kroki-plugin

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · MKDOCS-KROKI-PLUGI

mkdocs-kroki-plugin

web-frameworkpythonv1.6.0

Install

3.7s avg

Import

908ms

Disk

38MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.6.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.946s · 38.9MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 3.7s · import 0.869s · 40MB

38MB installed

● package 38MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

KrokiPlugin

✓ from kroki.plugin import KrokiPlugin

Add `kroki` to your `mkdocs.yml` plugins section and use fenced code blocks with `kroki-<diagram_type>` to embed diagrams in your Markdown files.

# mkdocs.yml site_name: My Docs with Kroki plugins: - kroki: server_url: https://kroki.io # Optional, default is https://kroki.io # docs/index.md # Example BlockDiag diagram ```kroki-blockdiag blockdiag { blockdiag -> generates -> "block-diagrams"; blockdiag -> is -> "very easy!"; blockdiag [color = "greenyellow"]; "block-diagrams" [color = "pink"]; "very easy!" [color = "orange"]; } ``` # To run: # mkdocs serve

Debug

Known issues

breakingConfiguration options were renamed and deprecated options removed in v1.0.0 to align with MkDocs conventions. For example, `ServerURL` became `server_url`, and options like `Enablebpmn` or `DownloadImages` were removed.

fix

Update your `mkdocs.yml` configuration to use `snake_case` for options and remove any deprecated settings. Refer to the plugin's README for the latest configuration schema.

affects: >=1.0.0

gotchaThe plugin's documentation suggests considering migration to ProperDocs, a fork of MkDocs, which may simplify future updates.

fix

Evaluate ProperDocs as a potential long-term solution for your documentation setup if you encounter complex upgrade paths or specific feature needs not met by vanilla MkDocs and its plugins.

affects: All

gotchaTheme-aware styles (`styles_light`, `styles_dark`) for diagrams require `http_method: POST` and `tag_format: img` to function correctly, particularly with themes like Material for MkDocs. Other `tag_format` settings (`object`, `svg`) will fall back to light-mode styles only with a warning.

fix

Ensure `http_method` is set to `POST` and `tag_format` is `img` in your plugin configuration when using `styles_light` or `styles_dark` for optimal theme integration.

affects: >=1.5.0

gotchaOlder versions (prior to v1.6.0) might incorrectly skip diagrams that appear after code blocks with unrecognized attributes due to a fence regex issue.

fix

Upgrade to `mkdocs-kroki-plugin` version 1.6.0 or newer to ensure all diagrams are correctly parsed and rendered, even when preceded by code blocks with unusual attributes.

affects: <1.6.0

gotchaWhen running a local Kroki server via Docker, its default port (often 8000) can conflict with `mkdocs serve`'s default port, leading to startup issues.

fix

Change the default port for either your local Kroki Docker instance or `mkdocs serve` (e.g., `mkdocs serve -a 0.0.0.0:8001`). Configure `server_url` in `mkdocs.yml` to point to the correct Kroki server address.

affects: All

Errors

Common errors & fixes

Broken images or missing diagrams in Backstage TechDocs site after upgrade.

Specific issues with how Backstage TechDocs handles local asset paths or `object` tags generated by the plugin in older versions. For example, `0.8.1` switched to `<object>` tags which caused problems for Backstage.

fix

Upgrade `mkdocs-kroki-plugin` to the latest version. If using `mkdocs-techdocs-core`, ensure it's also updated. Check for configuration regarding `tag_format` (default `img` is usually more compatible than `object` or `svg` in some environments) and `http_method: POST` for downloading images.

Diagrams are not displayed at all, just showing the code fence.

Incorrect plugin activation in `mkdocs.yml`, a non-reachable Kroki server, syntax errors in the diagram code, or a regex parsing issue in older versions.

fix

Verify the plugin is correctly listed under `plugins:` in `mkdocs.yml`. Check that your diagram syntax is valid for the specified Kroki type. Ensure the `server_url` is correct and reachable (default is `https://kroki.io`). Upgrade to the latest plugin version to address parsing fixes.

MkDocs build fails with 'KeyError' or 'TypeError' related to plugin configuration after update.

This typically occurs after upgrading to v1.0.0 where configuration option names changed from PascalCase to snake_case and some options were removed.

fix

Update your `mkdocs.yml` to use the new snake_case configuration keys (e.g., `server_url` instead of `ServerURL`) and remove any deprecated configuration options. Refer to the plugin's documentation for the updated config schema.

HTTP timeout errors when rendering large diagrams.

The default HTTP request timeout to the Kroki server might not be sufficient for complex or large diagrams that take longer to process.

fix

Increase the `request_timeout` option in your `mkdocs.yml` plugin configuration (e.g., `request_timeout: 60`). `server_url: !ENV [KROKI_SERVER_URL, 'https://kroki.io']`

Upgrade

Version history

1.6.0latest on PyPI · released Apr 13, 2026

Audit

Dependencies

mkdocsrequiredCore dependency for MkDocs plugin functionality.

httpxrequiredUsed for making HTTP requests to the Kroki server.

resultrequiredLikely used for functional programming patterns and error handling.

defusedxmlrequiredFor safely parsing XML, potentially for SVG output from Kroki.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin#readme ↗

packagehttps://pypi.org/project/mkdocs-kroki-plugin/ ↗

docshttps://github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin#readme ↗