MkDocs Kroki Plugin

1.6.0 · active · verified Thu Apr 16

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.

Common errors

```
Broken images or missing diagrams in Backstage TechDocs site after upgrade.
```
cause 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.
```
cause 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.
```
cause 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.
```
cause 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']`

Warnings

breaking Configuration 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.
gotcha The 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.
gotcha Theme-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.
gotcha Older 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.
gotcha When 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.

Install

pip install mkdocs-kroki-plugin Install with pip

Imports

KrokiPlugin
```
from kroki.plugin import KrokiPlugin
```

Quickstart

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

view raw JSON →