Metadata-Version: 2.4
Name: mkdocs-kroki-plugin
Version: 1.3.1
Summary: MkDocs plugin for Kroki-Diagrams
Project-URL: Documentation, https://github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin#readme
Project-URL: Issues, https://github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin/issues
Project-URL: Source, https://github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin
Author-email: Timo Reymann <mail@timo-reymann.de>, Antonia Siegert <oniboni@mailbox.org>, Benjamin Bittner <benjamin.bittner@avateam.com>
License-Expression: MIT
License-File: LICENSE
Keywords: diagram,kroki,markdown,mkdocs,python
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: MkDocs
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.10
Requires-Dist: defusedxml>=0.7.1
Requires-Dist: httpx>=0.24.0
Requires-Dist: mkdocs>=1.5.0
Requires-Dist: result>=0.17.0
Description-Content-Type: text/markdown

# mkdocs-kroki-plugin

[![PyPI version](https://badge.fury.io/py/mkdocs-kroki-plugin.svg)](https://badge.fury.io/py/mkdocs-kroki-plugin)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/mkdocs-kroki-plugin)](https://pypi.org/project/mkdocs-kroki-plugin/)
[![Test Status](https://github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin/actions/workflows/test.yml/badge.svg)](https://github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin/actions/workflows/test.yml)
[![Lint Status](https://github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin/actions/workflows/lint.yml/badge.svg)](https://github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin/actions/workflows/lint.yml)
[![Python versions](https://img.shields.io/pypi/pyversions/mkdocs-kroki-plugin.svg)](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`)<br> 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<br>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<br>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`, `text`, `line`, `background`). See [Global Styles](#global-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-`<Module>` 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"
        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).

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`**          | ✅        | ✅           | ✅       | ❌        | ❌           | ❌       | ❌  | ✅           |
| **`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.

## Contributors

[![Contributors](https://contrib.rocks/image?repo=AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin)](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 <version>
```

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)
