https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin
MkDocs plugin for Kroki-Diagrams
https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin
diagram diagramming kroki mkdocs mkdocs-plugin
Last synced: about 2 months ago
JSON representation
MkDocs plugin for Kroki-Diagrams
- Host: GitHub
- URL: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin
- Owner: AVATEAM-IT-SYSTEMHAUS
- License: mit
- Created: 2021-04-13T09:57:17.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2026-04-03T01:37:22.000Z (about 2 months ago)
- Last Synced: 2026-04-03T11:25:18.998Z (about 2 months ago)
- Topics: diagram, diagramming, kroki, mkdocs, mkdocs-plugin
- Language: Python
- Homepage:
- Size: 357 KB
- Stars: 62
- Watchers: 4
- Forks: 30
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: .github/SECURITY.md
Awesome Lists containing this project
README
# mkdocs-kroki-plugin
[](https://badge.fury.io/py/mkdocs-kroki-plugin)
[](https://pypi.org/project/mkdocs-kroki-plugin/)
[](https://github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin/actions/workflows/test.yml)
[](https://github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin/actions/workflows/lint.yml)
[](https://pypi.org/project/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`:
```yaml
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/` |
| `file_types` | File types you want to use
Note: not all file formats work with all diagram types | `[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](#global-styles). | (none) |
| `styles_light` | Style map applied in light mode. Use together with `styles_dark` for theme-aware diagrams. See [Theme-Aware Styles](#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](#theme-aware-styles). | (none) |
Example:
```yaml
- 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:**
```yaml
- kroki:
cache_dir: .cache/kroki # Store cache in project directory
```
## Usage
Use code-fences with a tag of kroki-`` to replace the code with the wanted diagram.
[Diagram options](https://docs.kroki.io/kroki/setup/diagram-options/) can be set as well.
Example for BlockDiag:
````markdown
```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:
````markdown
```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
````markdown
```kroki-plantuml {display-width=500px}
@startuml
Alice -> Bob: Hello
Bob --> Alice: Hi!
@enduml
```
````
You can use both width and height together:
````markdown
```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`.
````markdown
```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`:
```yaml
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`:
````markdown
```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:
```css
background: light-dark(white, #333);
```
- When only one color is set, it applies as a simple background:
```css
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.
```yaml
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`:
````markdown
```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.
```yaml
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 `![]()
` tags using [MkDocs Material's light/dark image feature](https://squidfunk.github.io/mkdocs-material/reference/images/#light-and-dark-mode):
```html
```
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](#support-matrix))
## Contributors
[](https://github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin/graphs/contributors)
> Want to appear in the list of contributors?
>
> Get started by reading the [Contribution Guidelines](./CONTRIBUTING.md)
## See Also
Diagram examples can be found [here](https://kroki.io/examples.html).
More information about installing a self-manged Kroki-Service [here](https://docs.kroki.io/kroki/setup/install/).
More Plugins for MkDocs can be found [here](http://www.mkdocs.org/user-guide/plugins/)
## Pre-Release-Versions
Install the newest pre-release version using pip:
`pip install -i https://test.pypi.org/simple/ mkdocs-kroki-plugin`
## Development
### Setup
```sh
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:
```sh
uv run pre-commit install
```
To run all hooks manually:
```sh
uv run pre-commit run --all-files
```
### Testing
Run tests:
```sh
uv run pytest
```
Run tests with coverage:
```sh
uv run pytest --cov
```
### Linting & Formatting
Run ruff for linting and formatting:
```sh
uv run ruff check .
uv run ruff format .
```
### Type Checking
Run mypy:
```sh
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:
```sh
./release.py
```
For example:
```sh
./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)