### Install mkdocs-kroki-plugin

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/README.md

Install the plugin using pip. This is the first step to enable Kroki diagram integration.

```bash
pip install mkdocs-kroki-plugin
```

--------------------------------

### Install Pre-Release Version

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/README.md

Install the latest pre-release version of the mkdocs-kroki-plugin using pip from the specified test PyPI index.

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

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/README.md

Install the pre-commit hooks to automate linting, type checking, and testing on each commit. Run this command in the project's root directory.

```sh
uv run pre-commit install
```

--------------------------------

### mkdocs.yml Inline SVG Example

Source: https://context7.com/avateam-it-systemhaus/mkdocs-kroki-plugin/llms.txt

Configuration example for mkdocs.yml to enable inline SVG rendering for Kroki diagrams, which automatically forces http_method to POST.

```yaml
# mkdocs.yml — inline SVG example (forces http_method: POST automatically)
plugins:
  - kroki:
      tag_format: svg
      file_types: [svg]
```

--------------------------------

### Preview Playground with Mkdocs

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/README.md

Start a local MkDocs development server to preview the documentation playground. This command is useful for testing changes in a live environment.

```sh
uv run task playground:mkdocs
```

--------------------------------

### Clone Repository and Sync Dependencies

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/README.md

Clone the project repository and synchronize development dependencies using 'uv'. This is the initial setup step for development.

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

--------------------------------

### Sequence Diagram: PlantUML Example

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/playground/docs/diagrams.md

A basic sequence diagram example using PlantUML syntax, depicting user interaction with a web browser, server, and database. PlantUML rendering must be enabled.

```plantuml
@startuml
actor User
participant "Web Browser" as Browser
participant "Web Server" as Server
database "Database" as DB

User -> Browser: Enter URL
Browser -> Server: HTTP Request
Server -> DB: Query data
DB --> Server: Return data
Server --> Browser: HTTP Response
Browser --> User: Display page
@enduml
```

--------------------------------

### Create Serial Cable Wiring Diagram

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/playground/docs/hardware.md

Use WireViz to create wiring harness documentation from YAML descriptions. This example defines a serial cable with D-Sub and Molex connectors.

```wireviz
connectors:
  X1:
    type: D-Sub
    subtype: female
    pincount: 9
    pins: [1, 2, 3, 4, 5]
    pinlabels: [GND, TX, RX, VCC, EN]
  X2:
    type: Molex KK 254
    subtype: female
    pincount: 4
    pins: [1, 2, 3, 4]
    pinlabels: [GND, Signal, VCC, EN]

cables:
  W1:
    gauge: 0.25 mm2
    length: 0.3
    color_code: DIN
    wirecount: 4
    colors: [BK, RD, GN, YE]

connections:
  -
    - X1: [1, 2, 4, 5]
    - W1: [1, 2, 3, 4]
    - X2: [1, 2, 3, 4]
```

--------------------------------

### Kroki Image Context and Modes

Source: https://context7.com/avateam-it-systemhaus/mkdocs-kroki-plugin/llms.txt

Illustrates the creation of a KrokiImageContext for different modes (GET and POST). In GET mode, a network call is not made and a URL is returned. In POST mode, a local filename is returned.

```python
kroki_ctx = KrokiImageContext(
    kroki_type="mermaid",
    options={},
    plugin_options={},
    data=Ok("graph LR\n  A --> B"),
)

# In POST mode the result is a local filename (e.g. "kroki-generated-<uuid>.svg")
# In GET mode the result is a full https://kroki.io/... URL
# result = asyncio.run(client.get_image_url(kroki_ctx, mkdocs_event_context))
# print(result.unwrap().url)
# → https://kroki.io/mermaid/svg/eNpLy8kvTgQABgQB-A==
```

--------------------------------

### Example Release Script Usage

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/README.md

Provide a specific version number (e.g., 1.2.3) to the release script to create a new release. The script validates the version format and performs necessary Git operations.

```sh
./release.py 1.2.3
```

--------------------------------

### KrokiClient for HTTP Communication

Source: https://context7.com/avateam-it-systemhaus/mkdocs-kroki-plugin/llms.txt

Instantiate KrokiClient for interacting with the Kroki server via GET or POST methods. Handles URL construction for GET and JSON payload with caching for POST. Requires diagram types and cache configuration.

```python
# GET mode: constructs a URL, nothing is downloaded
# POST mode: downloads the image and saves it next to the page

# The client is instantiated by KrokiPlugin.on_config; direct use example:
import asyncio
from kroki.cache import KrokiCache
from kroki.client import KrokiClient
from kroki.diagram_types import KrokiDiagramTypes
from kroki.common import KrokiImageContext
from result import Ok

diagram_types = KrokiDiagramTypes(
    fence_prefix="kroki-",
    file_types=["svg"],
    file_type_overrides={},
    blockdiag_enabled=False,
    bpmn_enabled=False,
    excalidraw_enabled=False,
    mermaid_enabled=True,
    diagramsnet_enabled=False,
)

client = KrokiClient(
    server_url="https://kroki.io",
    http_method="GET",
    user_agent="my-tool/1.0",
    timeout_seconds=30,
    diagram_types=diagram_types,
    cache=KrokiCache(),
)
```

--------------------------------

### Create Sensor Harness Wiring Diagram

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/playground/docs/hardware.md

Use WireViz to create wiring harness documentation from YAML descriptions. This example defines a sensor harness connecting multiple sensors to a microcontroller.

```wireviz
connectors:
  MCU:
    type: Pin Header
    subtype: male
    pincount: 6
    pins: [1, 2, 3, 4, 5, 6]
    pinlabels: [3V3, GND, SDA, SCL, INT, RST]
  Sensor1:
    type: JST-PH
    subtype: female
    pincount: 4
    pins: [1, 2, 3, 4]
    pinlabels: [VCC, GND, SDA, SCL]
  Sensor2:
    type: JST-PH
    subtype: female
    pincount: 4
    pins: [1, 2, 3, 4]
    pinlabels: [VCC, GND, SDA, SCL]

cables:
  C1:
    wirecount: 4
    gauge: 0.14 mm2
    length: 0.15
    colors: [RD, BK, YE, GN]
  C2:
    wirecount: 4
    gauge: 0.14 mm2
    length: 0.25
    colors: [RD, BK, YE, GN]

connections:
  -
    - MCU: [1, 2, 3, 4]
    - C1: [1, 2, 3, 4]
    - Sensor1: [1, 2, 3, 4]
  -
    - MCU: [1, 2, 3, 4]
    - C2: [1, 2, 3, 4]
    - Sensor2: [1, 2, 3, 4]
```

--------------------------------

### Configure Kroki Plugin with Server URL and File Types

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/README.md

Configure the Kroki plugin to specify the server URL, supported file types, and file type overrides for diagram generation. This example also shows how to enable fail-fast behavior in CI environments.

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

--------------------------------

### C4 PlantUML System Context Diagram

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/playground/docs/index.md

Create a C4 System Context diagram using PlantUML syntax. This example includes necessary includes for C4 model elements.

```c4plantuml
!include <C4/C4_Context>
!include <C4/C4_Container>

title System Context diagram for Kroki Plugin

Person(developer, "Developer", "Creates documentation with diagrams")
Person(reader, "Reader", "Consumes the documentation")

System_Boundary(docs, "Documentation System") {
    Container(mkdocs, "MkDocs", "Python", "Static site generator")
    Container(plugin, "Kroki Plugin", "Python", "Renders diagrams")
    ContainerDb(output, "Static Site", "HTML/CSS/JS", "Published documentation")
}

System_Ext(kroki, "Kroki Server", "Renders diagrams to images")

Rel(developer, mkdocs, "Writes markdown with")
BiRel(mkdocs, plugin, "Processes diagrams via")
BiRel(plugin, kroki, "Generates images from")
Rel(mkdocs, output, "Builds")
Rel(reader, output, "Reads")
```

--------------------------------

### KrokiClient - HTTP Communication with the Kroki Server

Source: https://context7.com/avateam-it-systemhaus/mkdocs-kroki-plugin/llms.txt

`KrokiClient` handles both HTTP methods. In GET mode it constructs a URL with zlib-compressed, base64url-encoded diagram data. In POST mode it sends `{"diagram_source": ..., "diagram_options": ...}` as JSON, stores the response in the cache, and writes the file to the MkDocs build directory.

```APIDOC
## `KrokiClient` — HTTP Communication with the Kroki Server

`KrokiClient` handles both HTTP methods. In GET mode it constructs a URL with zlib-compressed, base64url-encoded diagram data. In POST mode it sends `{"diagram_source": ..., "diagram_options": ...}` as JSON, stores the response in the cache, and writes the file to the MkDocs build directory.

```python
# GET mode: constructs a URL, nothing is downloaded
# POST mode: downloads the image and saves it next to the page

# The client is instantiated by KrokiPlugin.on_config; direct use example:
import asyncio
from kroki.cache import KrokiCache
from kroki.client import KrokiClient
from kroki.diagram_types import KrokiDiagramTypes
from kroki.common import KrokiImageContext
from result import Ok

diagram_types = KrokiDiagramTypes(
    fence_prefix="kroki-",
    file_types=["svg"],
    file_type_overrides={},
    blockdiag_enabled=False,
    bpmn_enabled=False,
    excalidraw_enabled=False,
    mermaid_enabled=True,
    diagramsnet_enabled=False,
)

client = KrokiClient(
    server_url="https://kroki.io",
    http_method="GET",
    user_agent="my-tool/1.0",
    timeout_seconds=30,
    diagram_types=diagram_types,
    cache=KrokiCache(),
)
```
```

--------------------------------

### Vega-Lite Scatter Plot

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/playground/docs/data-visualization.md

Create an interactive scatter plot using Vega-Lite. This example visualizes sales data by month and region, encoding color and size by relevant fields.

```vegalite
{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "description": "Quarterly revenue by region",
  "data": {
    "values": [
      {"month": "Jan", "sales": 28, "region": "North"},
      {"month": "Feb", "sales": 55, "region": "North"},
      {"month": "Mar", "sales": 43, "region": "North"},
      {"month": "Apr", "sales": 91, "region": "North"},
      {"month": "Jan", "sales": 81, "region": "South"},
      {"month": "Feb", "sales": 53, "region": "South"},
      {"month": "Mar", "sales": 19, "region": "South"},
      {"month": "Apr", "sales": 87, "region": "South"}
    ]
  },
  "mark": "point",
  "encoding": {
    "x": {"field": "month", "type": "nominal", "title": "Month"},
    "y": {"field": "sales", "type": "quantitative", "title": "Sales"},
    "color": {"field": "region", "type": "nominal"},
    "size": {"field": "sales", "type": "quantitative"}
  }
}
```

--------------------------------

### State Machine Diagram: Basic Workflow

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/playground/docs/diagrams.md

Represents a simple state machine with transitions for start, idle, processing, success, error, retry, and failure states using Nomnoml syntax. Ensure Nomnoml rendering is enabled.

```nomnoml
[<start> start] -> [Idle]
[Idle] -> [Processing]
[Processing] -> [Success]
[Processing] -> [Error]
[Success] -> [Idle]
[Error] -> [Retry]
[Retry] -> [Processing]
[Retry] -> [Failed]
[Failed] -> [<end> end]
```

--------------------------------

### Mermaid with Injected Styles

Source: https://context7.com/avateam-it-systemhaus/mkdocs-kroki-plugin/llms.txt

Mermaid diagrams will have styles injected using `%%{init: {"theme":"base","themeVariables":{...}}}%%`. This example demonstrates the injection mechanism.

```mermaid
```kroki-mermaid
graph TD
  A[Box] --> B[Another Box]
```
```

--------------------------------

### PlantUML with Injected Styles

Source: https://context7.com/avateam-it-systemhaus/mkdocs-kroki-plugin/llms.txt

PlantUML diagrams will have styles injected as `skinparam` directives. This example shows how global styles are applied.

```plantuml
```kroki-plantuml
@startuml
' Plugin injects: skinparam RectangleBackgroundColor #e6f3ff
'                 skinparam ArrowColor #666666
'                 skinparam BackgroundColor #ffffff  ... etc.
Alice -> Bob: Hello
note right: A styled note
@enduml
```
```

--------------------------------

### WaveDrom SPI Communication Diagram

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/playground/docs/data-visualization.md

Render a digital timing diagram for SPI communication using WaveDrom. This example shows CLK, MOSI, MISO, and SS signals with data transitions.

```wavedrom
{ "signal": [
  { "name": "CLK",  "wave": "p........" },
  { "name": "MOSI", "wave": "x.345678x", "data": ["D7","D6","D5","D4","D3","D2","D1","D0"] },
  { "name": "MISO", "wave": "x.345678x", "data": ["Q7","Q6","Q5","Q4","Q3","Q2","Q1","Q0"] },
  { "name": "SS",   "wave": "10.......1" }
]}

```

--------------------------------

### Development and Testing Commands

Source: https://context7.com/avateam-it-systemhaus/mkdocs-kroki-plugin/llms.txt

A collection of commands for setting up the development environment, running tests, linting, type checking, previewing the playground, and cutting a release for the mkdocs-kroki-plugin.

```bash
# Clone and install dependencies
git clone https://github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin.git
cd mkdocs-kroki-plugin
uv sync

# Run the full test suite
uv run pytest

# Run with coverage report
uv run pytest --cov

# Linting and formatting
uv run ruff check .
uv run ruff format .

# Type checking
uv run --group types mypy kroki

# Live-preview the playground docs (requires running Kroki server)
uv run task playground:mkdocs

# Cut a release (bumps version, commits, tags, pushes, opens GitHub release page)
./release.py 1.7.0
```

--------------------------------

### Preview Playground with TechDocs CLI

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/README.md

Use the techdocs-cli to preview the documentation playground. This is an alternative method for local development and testing.

```sh
uv run task playground:techdocs
```

--------------------------------

### Server Rack Layout Diagram (rackdiag)

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/playground/docs/network.md

Defines a server rack layout, specifying the units (U) and types of equipment installed in each slot.

```rackdiag
rackdiag {
  16U;

  1: UPS [2U, color = "lime"];
  3: DB Server [color = "pink"];
  4: Web Server 1 [color = "lightblue"];
  5: Web Server 2 [color = "lightblue"];
  6: Patch Panel [1U];
  9: Core Switch [color = "lightyellow"];
  10: Edge Switch [color = "lightyellow"];
  15: PDU [1U, color = "orange"];
  16: PDU [1U, color = "orange"];
}
```

--------------------------------

### Basic mkdocs.yml Configuration

Source: https://context7.com/avateam-it-systemhaus/mkdocs-kroki-plugin/llms.txt

Configure the Kroki plugin in your mkdocs.yml file. Set the server URL, HTTP method, and file types.

```yaml
plugins:
  - search
  - kroki:
      server_url: !ENV [KROKI_SERVER_URL, 'https://kroki.io']
      http_method: POST          # POST downloads images; GET constructs URLs
      file_types:
        - svg
        - png
      file_type_overrides:
        mermaid: png             # override per diagram type
      fail_fast: !ENV [CI, false]
      cache_dir: .cache/kroki   # optional; defaults to $XDG_CACHE_HOME/kroki
```

--------------------------------

### Generate UART Transmitter Symbol

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/playground/docs/hardware.md

Use Symbolator to generate hardware component symbols from VHDL entity declarations. This example defines a UART transmitter.

```symbolator
library ieee;
use ieee.std_logic_1164.all;

entity uart_tx is
  port (
    clk       : in  std_logic;
    reset     : in  std_logic;
    tx_data   : in  std_logic_vector(7 downto 0);
    tx_start  : in  std_logic;
    tx_serial : out std_logic;
    tx_busy   : out std_logic;
    tx_done   : out std_logic
  );
end entity;
```

--------------------------------

### Generate ALU Component Symbol

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/playground/docs/hardware.md

Use Symbolator to generate hardware component symbols from VHDL entity declarations. This example defines an Arithmetic Logic Unit.

```symbolator
library ieee;
use ieee.std_logic_1164.all;

entity ALU is
  port (
    clk    : in std_logic;
    reset  : in std_logic;
    op     : in std_logic_vector(1 downto 0);
    a      : in std_logic_vector(7 downto 0);
    b      : in std_logic_vector(7 downto 0);
    result : out std_logic_vector(7 downto 0);
    carry  : out std_logic;
    zero   : out std_logic
  );
end entity;
```

--------------------------------

### Full mkdocs.yml Configuration Reference

Source: https://context7.com/avateam-it-systemhaus/mkdocs-kroki-plugin/llms.txt

A comprehensive configuration reference for mkdocs-kroki-plugin, covering all available options for server URL, diagram types, styling, and more.

```yaml
# mkdocs.yml — full configuration reference
plugins:
  - kroki:
      server_url: https://kroki.io          # or self-hosted instance
      fence_prefix: 'kroki-'                # prefix on code fence lang tag
      enable_block_diag: true               # blockdiag, seqdiag, actdiag, nwdiag …
      enable_bpmn: true
      enable_excalidraw: true
      enable_mermaid: true
      enable_diagramsnet: false             # diagrams.net (draw.io); off by default
      http_method: GET                      # GET (URL-encoded) or POST (downloads file)
      request_timeout: 30                   # seconds; increase for slow servers
      user_agent: 'kroki.plugin/1.6.0'
      file_types: [svg]                     # preferred output formats, in priority order
      file_type_overrides:
        plantuml: png
        mermaid: svg
      tag_format: img                       # img | object | svg
      fail_fast: false
      cache_dir: null                       # null = auto-detect via XDG/HOME/tmp
      diagram_background_color_light: white
      diagram_background_color_dark: '#1e1e1e'
      styles:
        box:
          fill: '#e6f3ff'
          stroke: '#0066cc'
      styles_light:
        box:
          fill: '#e8f4fd'
      styles_dark:
        box:
          fill: '#1a2a3a'
```

--------------------------------

### Activate mkdocs-kroki-plugin in mkdocs.yml

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/README.md

Activate the plugin in your mkdocs.yml configuration file. Ensure it is listed under the 'plugins' section.

```yaml
plugins:
    ...
      - kroki:
```

--------------------------------

### Infrastructure Overview Diagram (d2)

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/playground/docs/network.md

Provides an infrastructure overview including users, CDN, load balancer, application tier, and database tier.

```d2
direction: right

users: Users {
  shape: person
  style.multiple: true
}

cdn: CDN {
  shape: cloud
}

lb: Load Balancer {
  shape: hexagon
}

app_tier: Application Tier {
  web1: Web Server 1 {
    shape: rectangle
  }
  web2: Web Server 2 {
    shape: rectangle
  }
  web3: Web Server 3 {
    shape: rectangle
  }
}

db_tier: Database Tier {
  primary: Primary DB {
    shape: cylinder
  }
  replica: Replica DB {
    shape: cylinder
  }
}

users -> cdn: HTTPS
cdn -> lb: Forward
lb -> app_tier.web1
lb -> app_tier.web2
lb -> app_tier.web3
app_tier.web1 -> db_tier.primary: Query
app_tier.web2 -> db_tier.primary: Query
app_tier.web3 -> db_tier.primary: Query
db_tier.primary -> db_tier.replica: Replicate
```

--------------------------------

### First Activity Diagram

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/playground/docs/fence-after-code.md

An activity diagram illustrating a user opening an application, filling a form, and the system validating input and storing a record. This diagram is styled by the kroki plugin.

```plantuml
@startuml

|User|
start
:Open the application;
:Fill in the form;

|System|
:Validate input;
:Store the record;

stop

@enduml
```

--------------------------------

### Load PlantUML from File

Source: https://context7.com/avateam-it-systemhaus/mkdocs-kroki-plugin/llms.txt

Use the `@from_file:` directive to load PlantUML source from an external file. Ensure the file path is relative to the `docs_dir`.

```markdown
<!-- docs/architecture.md -->
The system overview is generated from a PlantUML source file:

```kroki-plantuml
@from_file:assets/system-overview.puml
```

<!-- docs/assets/system-overview.puml -->
@startuml
package "Frontend" {
  [React App]
}
package "Backend" {
  [API Server]
  [Worker]
}
database "PostgreSQL" {
  [users]
  [jobs]
}
[React App] --> [API Server] : REST
[API Server] --> [Worker] : queue
[API Server] --> [users]
[Worker] --> [jobs]
@enduml
```

--------------------------------

### C4 Context Diagram with MkDocs Kroki Plugin

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/tests/data/happy_path/docs/index.md

Use this snippet to generate a C4 System Context diagram. Ensure the MkDocs Kroki plugin is configured to handle PlantUML syntax.

```c4plantuml
!include <C4/C4_Context>
!include <C4/C4_Container>

title System Context diagram for MkDocs Kroki Plugin

Person(writer, "Technical Writer", "Writes documentaion in markdown")
Person(reader, "Audience", "Reads documentaion represented as a web page")

System_Boundary(builder, "Static Site Generation") {
    Container(mkdocs, "MkDocs", "python", "Static Site Generator")
    Container(plugin, "MkDocs Kroki Plugin", "python", "Handles fence block contents")

    ContainerDb(db, "Storage", "gh-pages, S3 or else", "Stores the generated static site")
}

System_Ext(kroki, "kroki.io", "Generates images from fenced contents")
System_Ext(site_host, "Site Host", "Serves the site contents to the audience")

Rel(writer, mkdocs, "use")
BiRel(mkdocs, plugin, "handle diagram blocks")

BiRel(plugin, kroki, "get image data")

Rel(mkdocs, db, "build")
Rel(site_host, db, "read")

Rel(site_host, reader, "serve")

```

--------------------------------

### KrokiDiagramTypes - Supported Diagram Types and File Extensions

Source: https://context7.com/avateam-it-systemhaus/mkdocs-kroki-plugin/llms.txt

`KrokiDiagramTypes` manages the mapping from fence language tags to Kroki diagram type identifiers and their supported output formats. Use `get_kroki_type()` to resolve a fence tag and `get_file_ext()` to get the configured output format.

```APIDOC
## `KrokiDiagramTypes` — Supported Diagram Types and File Extensions

`KrokiDiagramTypes` manages the mapping from fence language tags to Kroki diagram type identifiers and their supported output formats. Use `get_kroki_type()` to resolve a fence tag and `get_file_ext()` to get the configured output format.

```python
from kroki.diagram_types import KrokiDiagramTypes

dt = KrokiDiagramTypes(
    fence_prefix="kroki-",
    file_types=["svg", "png"],          # preference order
    file_type_overrides={"mermaid": "png"},
    blockdiag_enabled=True,
    bpmn_enabled=True,
    excalidraw_enabled=True,
    mermaid_enabled=True,
    diagramsnet_enabled=False,
)

# Resolve fence tag → kroki type
assert dt.get_kroki_type("kroki-plantuml") == "plantuml"
assert dt.get_kroki_type("kroki-mermaid")  == "mermaid"
assert dt.get_kroki_type("markdown")       is None   # not a kroki block
assert dt.get_kroki_type("kroki-unknown")  is None   # unsupported type

# Resolve output format
assert dt.get_file_ext("plantuml") == "svg"   # svg preferred and supported
assert dt.get_file_ext("mermaid")  == "png"   # override in effect
assert dt.get_file_ext("ditaa")    == "svg"

# All built-in base diagram types:
# bytefield, ditaa, erd, graphviz, nomnoml, plantuml, structurizr,
# c4plantuml, svgbob, vega, vegalite, wavedrom, pikchr, umlet, d2,
# dbml, tikz, symbolator, wireviz
# BlockDiag family (when enabled): blockdiag, seqdiag, actdiag, nwdiag, packetdiag, rackdiag
# Optional: bpmn, excalidraw, mermaid, diagramsnet
```
```

--------------------------------

### Configure Theme-Aware Styles for Kroki Diagrams

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/README.md

Use `styles_light` and `styles_dark` to define different diagram styles for light and dark modes. This requires MkDocs Material theme and specific configuration settings.

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

--------------------------------

### Self-Hosted Kroki Server Configuration

Source: https://context7.com/avateam-it-systemhaus/mkdocs-kroki-plugin/llms.txt

Configuration for using a self-hosted Kroki instance via mkdocs.yml, setting the server_url, http_method, and request_timeout. Also includes a docker run command for a self-hosted Kroki server.

```yaml
# mkdocs.yml — self-hosted Kroki
plugins:
  - kroki:
      server_url: !ENV [KROKI_SERVER_URL, 'https://kroki.io']
      http_method: POST
      request_timeout: 60
      fail_fast: !ENV [CI, false]
```

--------------------------------

### Self-Hosted Kroki Server Docker Run

Source: https://context7.com/avateam-it-systemhaus/mkdocs-kroki-plugin/llms.txt

Command to run a self-hosted Kroki server using Docker. This is useful for air-gapped environments or to remove dependency on the public Kroki server.

```bash
# docker-compose.yml excerpt for a self-hosted Kroki stack
# (see https://docs.kroki.io/kroki/setup/install/)
docker run -d -p 8000:8000 yuzutech/kroki

# Build docs against the local server
KROKI_SERVER_URL=http://localhost:8000 mkdocs build
```

--------------------------------

### Ditaa Deployment Pipeline Diagram

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/playground/docs/text-diagrams.md

Illustrate deployment pipelines using Ditaa by converting ASCII art into bitmap graphics.

```ditaa
  +----------+    +----------+    +----------+    +----------+
  |          |    |          |    |          |    |          |
  |  Commit  +--->+  Build   +--->+  Test    +--->+  Deploy  |
  |    {io}  |    |          |    |          |    |   {s}    |
  +----+-----+    +----+-----+    +----+-----+    +----+-----+
       |               |               |               |
       v               v               v               v
  +---------+    +---------+    +---------+    +---------+
  |  Git    |    | Artifact|    | Report  |    |  Prod   |
  |  Repo   |    | Storage |    |  cGRE   |    | Server  |
  |  {s}    |    |  {s}    |    |         |    |  {s}    |
  +---------+    +---------+    +---------+    +---------+

```

--------------------------------

### Mermaid Process Flow Diagram

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/playground/docs/index.md

Illustrate a process flow using Mermaid syntax. This diagram shows the steps from documentation writing to publishing.

```mermaid
graph TD
    A[Start Documentation] -->|Write Markdown| B(Add Diagram Code)
    B --> C{Choose Diagram Type}
    C -->|PlantUML| D[PlantUML Syntax]
    C -->|Mermaid| E[Mermaid Syntax]
    C -->|GraphViz| F[GraphViz Syntax]
    D --> G[Kroki Processing]
    E --> G
    F --> G
    G --> H[Generated Image]
    H --> I[Published Documentation]
```

--------------------------------

### Svgbob Simple Circuit Diagram

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/playground/docs/text-diagrams.md

Create simple circuit diagrams with components like resistors and capacitors using Svgbob.

```svgbob
     +10V
      |
      |
     .-.
     | | 4.7k
     | | 
     '-'
      |
      +------+-------o Vout
      |      |
     .-.    ===  100n
     | |    ---
     | | 10k|
     '-'     |
      |      |
      +------+ 
      |
     GND

```

--------------------------------

### Python Hello World Script

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/playground/docs/fence-after-code.md

A basic Python script that greets a given name or 'world' if no name is provided. It demonstrates standard input handling and function definition.

```python
import sys

def greet(name: str) -> None:
    print(f"Hello, {name}!")


if __name__ == "__main__":
    greet(sys.argv[1] if len(sys.argv) > 1 else "world")
```

--------------------------------

### Render Diagram from File using Kroki Plugin

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/README.md

Use the `@from_file:` directive within a Kroki code fence to render a diagram defined in an external file. Specify the path to the diagram file.

```markdown
```kroki-bpmn
@from_file:path/to/diagram.bpmn
```
```

--------------------------------

### Create a New Release

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/README.md

Execute the release script to create a new version of the plugin. This script automates version bumping, committing, tagging, and preparing for a GitHub release.

```sh
./release.py <version>
```

--------------------------------

### Web Application Component Diagram

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/playground/docs/uml.md

Visualizes the structure of a web application, showing packages for 'Web Application' and 'External Services', and a 'Database'. It details the dependencies and interactions between components like UI, Business Logic, and Data Access Layer. Use this for architectural overview.

```plantuml
@startuml
package "Web Application" {
  [User Interface] as UI
  [Business Logic] as BL
  [Data Access Layer] as DAL
}

package "External Services" {
  [Payment Gateway] as PG
  [Email Service] as ES
  [Analytics] as AN
}

database "Database" {
  [User Data]
  [Product Catalog]
  [Order History]
}

UI --> BL
BL --> DAL
DAL --> [User Data]
DAL --> [Product Catalog]
DAL --> [Order History]
BL --> PG : process payments
BL --> ES : send notifications
BL --> AN : track events
@enduml
```

--------------------------------

### mkdocs.yml Configuration for Kroki Plugin

Source: https://context7.com/avateam-it-systemhaus/mkdocs-kroki-plugin/llms.txt

Configure the kroki plugin in mkdocs.yml to specify HTTP method, tag format, and custom styles for light and dark themes.

```yaml
plugins:
  - kroki:
      http_method: POST
      tag_format: img
      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'
```

--------------------------------

### PlantUML Notes with Styles

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/playground/docs/styles.md

Demonstrates styling for different types of notes in PlantUML diagrams, including floating notes and notes attached to elements.

```plantuml
@startuml
note "This is a floating note" as N1

note left of Alice
  This is a note
  on several lines
end note

Alice -> Bob : hello
note right of Bob
  Bob thinks about
  the request
end note

Bob --> Alice : ok
note left
  This is another note
end note
@enduml
```

--------------------------------

### BPMN from External File

Source: https://context7.com/avateam-it-systemhaus/mkdocs-kroki-plugin/llms.txt

Embed a BPMN diagram by loading its source from an external file using the '@from_file' directive within the kroki-bpmn code fence.

```markdown
<!-- BPMN loaded from an external file -->
```kroki-bpmn
@from_file:assets/process.bpmn
```
```

--------------------------------

### Run All Pre-commit Hooks Manually

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/README.md

Execute all configured pre-commit hooks across all files in the repository. This is useful for ensuring code quality before committing.

```sh
uv run pre-commit run --all-files
```

--------------------------------

### Checkout Use Case Diagram

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/playground/docs/uml.md

Illustrates the checkout process in an e-commerce system, showing interactions between the Customer, Clerk, and system functionalities like Payment and Help. Use this to model user interactions and system processes.

```plantuml
@startuml
left to right direction
actor Customer
actor Clerk

rectangle Checkout {
  Customer -- (Checkout)
  (Checkout) .> (Payment) : includes
  (Help) .> (Checkout) : extends
  (Checkout) -- Clerk
}
@enduml
```

--------------------------------

### Mermaid Flowchart with Styles

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/playground/docs/styles.md

Applies global styles to a Mermaid flowchart, demonstrating how the `styles` configuration affects basic graph elements.

```mermaid
graph TD
    A[Customer Request] --> B{Valid?}
    B -->|Yes| C[Process Order]
    B -->|No| D[Return Error]
    C --> E[Send Confirmation]
    D --> F[Log Issue]
    E --> G[Done]
    F --> G
```

--------------------------------

### Structurizr for Web Application Architecture

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/playground/docs/data-modeling.md

Models a web application architecture using Structurizr DSL, defining users, containers, and their interactions.

```structurizr
workspace {
  model {
    user = person "User" "A user of the system"
    softwareSystem = softwareSystem "Online Store" {
      webapp = container "Web Application" "Delivers content" "React"
      api = container "API Server" "Handles business logic" "Node.js"
      database = container "Database" "Stores data" "PostgreSQL" "database"
      cache = container "Cache" "Session and query cache" "Redis" "database"
    }
    user -> webapp "Browses"
    webapp -> api "Makes API calls to"
    api -> database "Reads from and writes to"
    api -> cache "Caches data in"
  }
  views {
    container softwareSystem {
      include *
      autolayout lr
    }
  }
}
```

--------------------------------

### Configure Global Background Colors

Source: https://context7.com/avateam-it-systemhaus/mkdocs-kroki-plugin/llms.txt

Set global default background colors for light and dark themes in `mkdocs.yml`. These can be overridden per diagram.

```yaml
# mkdocs.yml — global background colors
plugins:
  - kroki:
      diagram_background_color_light: white
      diagram_background_color_dark: '#333333'
```

--------------------------------

### Include PlantUML Diagram from File

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/tests/data/happy_path/docs/index.md

Embed a PlantUML diagram by referencing an external file. The MkDocs Kroki plugin will process the specified file.

```plantuml
@from_file:assets/diagram.plantuml

```

--------------------------------

### Sequence Diagram: Authentication Flow

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/playground/docs/diagrams.md

Illustrates a typical authentication process between a browser, web server, and database using seqdiag syntax. Ensure seqdiag is enabled for rendering.

```seqdiag
seqdiag {
  browser  -> webserver [label = "GET /login"];
  browser <-- webserver [label = "Login Page"];
  browser  -> webserver [label = "POST /auth"];
  webserver -> database [label = "SELECT user"];
  webserver <-- database [label = "User data"];
  webserver -> webserver [label = "Validate credentials"];
  browser <-- webserver [label = "Set session cookie"];
  browser  -> webserver [label = "GET /dashboard"];
  webserver -> database [label = "Fetch user data"];
  webserver <-- database;
  browser <-- webserver [label = "Dashboard HTML"];
}
```

--------------------------------

### Project Development Timeline Gantt Chart

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/playground/docs/uml.md

Visualizes a project timeline with distinct phases like Planning, Development, Testing, and Deployment. It specifies tasks, durations, and dependencies between them. Use this for project management and scheduling.

```mermaid
gantt
    title Project Development Timeline
    dateFormat  YYYY-MM-DD
    section Planning
    Requirements gathering       :a1, 2024-01-01, 14d
    System design               :a2, after a1, 10d
    section Development
    Backend development         :b1, 2024-01-25, 30d
    Frontend development        :b2, 2024-02-05, 25d
    Database setup             :b3, 2024-01-25, 7d
    section Testing
    Unit testing               :c1, after b1, 10d
    Integration testing        :c2, after b2, 7d
    UAT                       :c3, after c2, 5d
    section Deployment
    Staging deployment         :d1, after c3, 2d
    Production deployment      :d2, after d1, 1d

```

--------------------------------

### Second Activity Diagram

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/playground/docs/fence-after-code.md

A second activity diagram showing a system receiving a request, a worker processing a task, and the system sending a response. This diagram should be rendered identically to the first.

```plantuml
@startuml

|System|
start
:Receive request;

|Worker|
:Process the task;
:Return result;

|System|
:Send response;

stop

@enduml
```

--------------------------------

### Configure Global Styles in mkdocs.yml

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/playground/docs/styles.md

Define a corporate color palette for diagram elements in your `mkdocs.yml` file. This configuration applies to various diagram types.

```yaml
plugins:
  - kroki:
      styles:
        box:
          fill: "#fff3e0"
          stroke: "#e65100"
        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: "13"
        line:
          stroke: "#f57c00"
```

--------------------------------

### Lint and Format Code with Ruff

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/README.md

Use ruff to check for linting errors and format the code according to project standards. Run these commands separately for checking and formatting.

```sh
uv run ruff check .
uv run ruff format .
```

--------------------------------

### Mermaid Sequence Diagram with Notes

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/playground/docs/styles.md

Shows how notes in Mermaid sequence diagrams are styled using `noteBkgColor`, `noteBorderColor`, and `noteTextColor`, reflecting the global styles.

```mermaid
sequenceDiagram
    actor User
    participant API
    participant DB

    User->>API: POST /orders
    Note right of User: Submits new order
    API->>DB: INSERT order
    Note over API,DB: Transactional write
    DB-->>API: OK
    API-->>User: 201 Created
    Note left of API: Returns order ID
```

--------------------------------

### Configure Global Background Colors for Kroki Diagrams

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/README.md

Set default background colors for all Kroki diagrams in `mkdocs.yml` to adapt to light and dark themes. This uses CSS `light-dark()` function for dynamic theming.

```yaml
plugins:
  - kroki:
      diagram_background_color_light: white
      diagram_background_color_dark: "#333"
```

--------------------------------

### Run Tests with Pytest

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/README.md

Execute all tests in the project using pytest. This command verifies the functionality of the plugin.

```sh
uv run pytest
```

--------------------------------

### MarkdownParser Fence Replacement Engine

Source: https://context7.com/avateam-it-systemhaus/mkdocs-kroki-plugin/llms.txt

Shows the initialization of MarkdownParser with diagram types and style injection. The replace_kroki_blocks method is called internally by KrokiPlugin.on_page_markdown to process Kroki fences.

```python
from kroki.parsing import MarkdownParser
from kroki.diagram_types import KrokiDiagramTypes
from kroki.styles import StyleInjector

diagram_types = KrokiDiagramTypes(
    fence_prefix="kroki-",
    file_types=["svg"],
    file_type_overrides={},
    blockdiag_enabled=False,
    bpmn_enabled=False,
    excalidraw_enabled=False,
    mermaid_enabled=True,
    diagramsnet_enabled=False,
)

parser = MarkdownParser(
    docs_dir="/docs",
    diagram_types=diagram_types,
    style_injector=StyleInjector({"box": {"fill": "#eee"}})
)

# replace_kroki_blocks is called internally by KrokiPlugin.on_page_markdown;
# the second argument is an async callback (ContentRenderer.render_kroki_block).
# The parser recognises both space-separated and {}-wrapped options:
#
#   ```kroki-mermaid display-width=500px no-style-inject=true
#   ```kroki-mermaid {display-width=500px display-align=center}
#
# Plugin options (display-width, display-height, display-align, bg-light,
# bg-dark, no-style-inject) are separated from Kroki diagram options before
# the context is built.
```

--------------------------------

### Configure Global Styles

Source: https://context7.com/avateam-it-systemhaus/mkdocs-kroki-plugin/llms.txt

Define diagram-type-agnostic styles in `mkdocs.yml` under the `styles` key. These are translated into native directives for each diagram type.

```yaml
# mkdocs.yml
plugins:
  - kroki:
      http_method: POST
      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: '#666666'
          label-background: '#ffffff'
        background:
          fill: '#ffffff'
```

--------------------------------

### ContentRenderer HTML Tag Generation

Source: https://context7.com/avateam-it-systemhaus/mkdocs-kroki-plugin/llms.txt

Demonstrates how ContentRenderer.render_kroki_block() generates HTML tags for Kroki diagrams based on the tag_format. It also shows the error output format when fail_fast is set to False.

```python
# tag_format="img"  → <img alt="Kroki" src="..." style="..." />
# tag_format="object" → <object id="Kroki" type="image/svg+xml" data="..."></object>
# tag_format="svg"  → <div><svg id="Kroki" ...>...</svg></div>  (inline, POST only)

# Error output when fail_fast=False:
# <details open="">
#   <summary>Diagram error!</summary>
#   <p>Parse error at line 3 ...</p>
#   <pre><code linenums="1">graph LR\n  ??? broken</code></pre>
# </details>
```

--------------------------------

### Set Diagram Width and Scale Height

Source: https://context7.com/avateam-it-systemhaus/mkdocs-kroki-plugin/llms.txt

Control the display width of a diagram using `display-width`. The height will scale proportionally. This option is applied inline and not sent to Kroki.

```kroki-plantuml
```kroki-plantuml {display-width=500px}
@startuml
Alice -> Bob: sync call
@enduml
```
```

--------------------------------

### Perform Type Checking with Mypy

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/README.md

Run mypy for static type checking on the 'kroki' module. This command helps catch type-related errors before runtime.

```sh
uv run --group types mypy kroki
```

--------------------------------

### Activity Diagram: Document Publishing Workflow

Source: https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin/blob/main/playground/docs/diagrams.md

Models a document publishing workflow with distinct lanes for user, approver, and system actions using Actdiag syntax. Requires Actdiag support.

```actdiag
actdiag {
  write -> review -> approve -> publish;

  lane user {
     label = "User"
     write [label = "Write content"];
     review [label = "Submit for review"];
  }
  lane approver {
     label = "Approver"
     approve [label = "Approve content"];
  }
  lane system {
     label = "System"
     publish [label = "Publish to site"];
  }
}
```