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

Install the plugin using pip:

pip install mkdocs-kroki-plugin

Activate the plugin in mkdocs.yml:

plugins:
    ...
      - kroki:

Example:

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

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

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
```

Want to appear in the list of contributors?

Get started by reading the Contribution Guidelines

Diagram examples can be found here.

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

More Plugins for MkDocs can be found here

Install the newest pre-release version using pip:

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

git clone git@github.com:AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin.git
cd mkdocs-kroki-plugin
uv sync

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

Run tests:

uv run pytest

Run tests with coverage:

uv run pytest --cov

Run ruff for linting and formatting:

uv run ruff check .
uv run ruff format .

Run mypy:

uv run --group types mypy kroki

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)