{"id":23087923,"url":"https://github.com/avateam-it-systemhaus/mkdocs-kroki-plugin","last_synced_at":"2026-04-04T02:01:39.261Z","repository":{"id":38109742,"uuid":"357504498","full_name":"AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin","owner":"AVATEAM-IT-SYSTEMHAUS","description":"MkDocs plugin for Kroki-Diagrams","archived":false,"fork":false,"pushed_at":"2026-04-03T01:37:22.000Z","size":366,"stargazers_count":62,"open_issues_count":1,"forks_count":30,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-04-03T11:25:18.998Z","etag":null,"topics":["diagram","diagramming","kroki","mkdocs","mkdocs-plugin"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AVATEAM-IT-SYSTEMHAUS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-04-13T09:57:17.000Z","updated_at":"2026-04-03T01:37:25.000Z","dependencies_parsed_at":"2024-05-19T19:46:17.953Z","dependency_job_id":"b018229f-1129-4bef-b418-24ceb75af625","html_url":"https://github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin","commit_stats":{"total_commits":47,"total_committers":10,"mean_commits":4.7,"dds":0.4042553191489362,"last_synced_commit":"5fd0518a78752777d257e8cdf12f6821caf7e2bc"},"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AVATEAM-IT-SYSTEMHAUS%2Fmkdocs-kroki-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AVATEAM-IT-SYSTEMHAUS%2Fmkdocs-kroki-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AVATEAM-IT-SYSTEMHAUS%2Fmkdocs-kroki-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AVATEAM-IT-SYSTEMHAUS%2Fmkdocs-kroki-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AVATEAM-IT-SYSTEMHAUS","download_url":"https://codeload.github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AVATEAM-IT-SYSTEMHAUS%2Fmkdocs-kroki-plugin/sbom","scorecard":{"id":7497,"data":{"date":"2025-08-11","repo":{"name":"github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin","commit":"8f8a6c433d8049e76b1a5cfb98be88a4f4ee4068"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3.6,"checks":[{"name":"Code-Review","score":2,"reason":"Found 1/5 approved changesets -- score normalized to 2","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/lint.yml:1","Warn: no topLevel permission defined: .github/workflows/python-publish-test.yml:1","Warn: no topLevel permission defined: .github/workflows/python-publish.yml:1","Warn: no topLevel permission defined: .github/workflows/test.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/lint.yml:24: update your workflow using https://app.stepsecurity.io/secureworkflow/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin/lint.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/lint.yml:25: update your workflow using https://app.stepsecurity.io/secureworkflow/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin/lint.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/python-publish-test.yml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin/python-publish-test.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/python-publish-test.yml:24: update your workflow using https://app.stepsecurity.io/secureworkflow/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin/python-publish-test.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/python-publish.yml:21: update your workflow using https://app.stepsecurity.io/secureworkflow/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin/python-publish.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/python-publish.yml:23: update your workflow using https://app.stepsecurity.io/secureworkflow/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin/python-publish.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:27: update your workflow using https://app.stepsecurity.io/secureworkflow/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin/test.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:29: update your workflow using https://app.stepsecurity.io/secureworkflow/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin/test.yml/main?enable=pin","Warn: pipCommand not pinned by hash: .github/workflows/lint.yml:30","Warn: pipCommand not pinned by hash: .github/workflows/lint.yml:31","Warn: pipCommand not pinned by hash: .github/workflows/python-publish-test.yml:29","Warn: pipCommand not pinned by hash: .github/workflows/python-publish-test.yml:30","Warn: pipCommand not pinned by hash: .github/workflows/python-publish.yml:28","Warn: pipCommand not pinned by hash: .github/workflows/python-publish.yml:29","Warn: pipCommand not pinned by hash: .github/workflows/test.yml:34","Warn: pipCommand not pinned by hash: .github/workflows/test.yml:35","Info:   0 out of   8 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   8 pipCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'main'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 29 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-14T13:53:51.400Z","repository_id":38109742,"created_at":"2025-08-14T13:53:51.400Z","updated_at":"2025-08-14T13:53:51.400Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31384847,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T01:22:39.193Z","status":"online","status_checked_at":"2026-04-04T02:00:07.569Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["diagram","diagramming","kroki","mkdocs","mkdocs-plugin"],"created_at":"2024-12-16T20:15:30.541Z","updated_at":"2026-04-04T02:01:39.217Z","avatar_url":"https://github.com/AVATEAM-IT-SYSTEMHAUS.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mkdocs-kroki-plugin\n\n[![PyPI version](https://badge.fury.io/py/mkdocs-kroki-plugin.svg)](https://badge.fury.io/py/mkdocs-kroki-plugin)\n[![PyPI - Downloads](https://img.shields.io/pypi/dm/mkdocs-kroki-plugin)](https://pypi.org/project/mkdocs-kroki-plugin/)\n[![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)\n[![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)\n[![Python versions](https://img.shields.io/pypi/pyversions/mkdocs-kroki-plugin.svg)](https://pypi.org/project/mkdocs-kroki-plugin/)\n\nThis is a MkDocs plugin to embed Kroki-Diagrams into your documentation.\n\n## Setup\n\nInstall the plugin using pip:\n\n`pip install mkdocs-kroki-plugin`\n\nActivate the plugin in `mkdocs.yml`:\n\n```yaml\nplugins:\n    ...\n      - kroki:\n```\n\n## Config\n\n| Key                              | Description                                                                                                                                   | Default                                       |\n|----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------|\n| `server_url`                     | URL of your kroki-Server                                                                                                                      | `!ENV [KROKI_SERVER_URL, 'https://kroki.io']` |\n| `fence_prefix`                   | Diagram prefix, set to an empty string to render all diagrams using Kroki                                                                     | `kroki-`                                      |\n| `enable_block_diag`              | Enable BlockDiag (and the related Diagrams)                                                                                                   | `true`                                        |\n| `enable_bpmn`                    | Enable BPMN                                                                                                                                   | `true`                                        |\n| `enable_excalidraw`              | Enable Excalidraw                                                                                                                             | `true`                                        |\n| `enable_mermaid`                 | Enable Mermaid                                                                                                                                | `true`                                        |\n| `enable_diagramsnet`             | Enable diagrams.net (draw.io)                                                                                                                 | `false`                                       |\n| `http_method`                    | Http method to use (`GET` or `POST`)\u003cbr\u003e Note: On `POST` the retrieved images are stored next to the including page in the build directory    | `GET`                                         |\n| `request_timeout`                | Timeout for HTTP requests in seconds. Increase this value if you encounter timeouts with large diagrams or overloaded kroki server instances. | `30`                                          |\n| `user_agent`                     | User agent for requests to the kroki server                                                                                                   | `kroki.plugin/\u003cversion\u003e`                      |\n| `file_types`                     | File types you want to use\u003cbr\u003eNote: not all file formats work with all diagram types \u003chttps://kroki.io/#support\u003e                              | `[svg]`                                       |\n| `file_type_overrides`            | Overrides for specific diagram types to set the desired file type                                                                             | `[]`                                          |\n| `tag_format`                     | How the image will be included in the resulting HTML (`img`, `object`, `svg`)                                                                 | `img`                                         |\n| `fail_fast`                      | Errors are raised as plugin errors                                                                                                            | `false`                                       |\n| `cache_dir`                      | Custom directory for caching rendered diagrams\u003cbr\u003eBy default uses `$XDG_CACHE_HOME/kroki`, `~/.cache/kroki`, or temp directory                | (automatic)                                   |\n| `diagram_background_color_light` | Background color for diagrams in light mode (CSS color value)                                                                                 | (none)                                        |\n| `diagram_background_color_dark`  | Background color for diagrams in dark mode (CSS color value)                                                                                  | (none)                                        |\n| `styles`                         | Global style map for diagram elements (`box`, `actor`, `note`, `package`, `text`, `line`, `background`). See [Global Styles](#global-styles).                    | (none)                                        |\n| `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)                                        |\n| `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)                                        |\n\nExample:\n\n```yaml\n  - kroki:\n      server_url: !ENV [ KROKI_SERVER_URL, 'https://kroki.io' ]\n      file_types:\n        - png\n        - svg\n      file_type_overrides:\n        mermaid: png\n      fail_fast: !ENV CI\n```\n\n### Caching\n\nThe plugin automatically caches rendered diagrams to improve build performance, especially useful during `mkdocs serve`\nwhen diagrams would otherwise be re-rendered on every file save.\n\n**Note:** Caching only applies when using `http_method: POST`. The GET method generates URLs pointing to the Kroki server\nand doesn't download diagram content.\n\n**How it works:**\n\n- Diagrams are cached based on their content, type, format, and options\n- Unchanged diagrams are retrieved from cache instead of being re-rendered\n- Both in-memory and file-based caching are used for optimal performance\n- **LRU strategy**: Frequently accessed diagrams stay in cache, unused ones expire after 3 days\n- Cache cleanup runs automatically on plugin initialization with minimal overhead\n\n**Cache location (fallback hierarchy):**\n\n1. `$XDG_CACHE_HOME/kroki` (if XDG_CACHE_HOME is set)\n2. `~/.cache/kroki` (if HOME is set)\n3. System temp directory + `/kroki` (final fallback)\n4. Custom location: Set `cache_dir` in plugin configuration to override\n\n**Example with custom cache directory:**\n\n```yaml\n  - kroki:\n      cache_dir: .cache/kroki  # Store cache in project directory\n```\n\n## Usage\n\nUse code-fences with a tag of kroki-`\u003cModule\u003e` to replace the code with the wanted diagram.\n\n[Diagram options](https://docs.kroki.io/kroki/setup/diagram-options/) can be set as well.\n\nExample for BlockDiag:\n\n````markdown\n```kroki-blockdiag no-transparency=false\nblockdiag {\n  blockdiag -\u003e generates -\u003e \"block-diagrams\";\n  blockdiag -\u003e is -\u003e \"very easy!\";\n\n  blockdiag [color = \"greenyellow\"];\n  \"block-diagrams\" [color = \"pink\"];\n  \"very easy!\" [color = \"orange\"];\n}\n```\n````\n\nYou can render diagram from file with `@from_file:` directive:\n\n````markdown\n```kroki-bpmn\n@from_file:path/to/diagram.bpmn\n```\n````\n\n### Display Options\n\nYou 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.\n\n#### Size Options\n\n````markdown\n```kroki-plantuml {display-width=500px}\n@startuml\nAlice -\u003e Bob: Hello\nBob --\u003e Alice: Hi!\n@enduml\n```\n````\n\nYou can use both width and height together:\n\n````markdown\n```kroki-blockdiag {display-width=400px display-height=200px}\nblockdiag {\n  A -\u003e B -\u003e C;\n}\n```\n````\n\n#### Alignment\n\nUse `display-align` to position diagrams horizontally. Valid values are `left`, `center`, and `right`.\n\n````markdown\n```kroki-mermaid {display-width=300px display-align=center}\ngraph LR\n    A[Start] --\u003e B[End]\n```\n````\n\nThis sets `display: block` and appropriate margin values:\n\n- `center`: `margin-left: auto; margin-right: auto`\n- `right`: `margin-left: auto; margin-right: 0`\n- `left`: `margin-left: 0; margin-right: auto`\n\n**Notes:**\n\n- Display options are handled by the plugin and are **not** sent to the Kroki server\n- Setting only `display-width` or `display-height` allows the browser to scale proportionally\n- These options work with all `tag_format` settings (`img`, `object`, `svg`)\n- Size values can be any valid CSS value (e.g., `500px`, `50%`, `auto`, `20em`)\n\n### Background Color\n\nYou 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.\n\n#### Global Configuration\n\nSet default background colors for all diagrams in `mkdocs.yml`:\n\n```yaml\nplugins:\n  - kroki:\n      diagram_background_color_light: white\n      diagram_background_color_dark: \"#333\"\n```\n\n#### Per-Diagram Override\n\nOverride the global settings for individual diagrams using `bg-light` and `bg-dark`:\n\n````markdown\n```kroki-plantuml {bg-light=#f5f5f5 bg-dark=#1a1a1a}\n@startuml\nAlice -\u003e Bob: Hello\n@enduml\n```\n````\n\n#### How It Works\n\n- When both light and dark colors are set, the plugin uses the CSS `light-dark()` function:\n  ```css\n  background: light-dark(white, #333);\n  ```\n- When only one color is set, it applies as a simple background:\n  ```css\n  background: white;\n  ```\n- When neither is set, no background style is applied\n\n**Notes:**\n\n- The `light-dark()` CSS function requires the page to have `color-scheme: light dark` set. MkDocs themes like Material for MkDocs handle this automatically.\n- Per-diagram options (`bg-light`, `bg-dark`) override global settings\n- You can set only one color per-diagram while inheriting the other from global config\n- Works with all `tag_format` settings (`img`, `object`, `svg`)\n\n### Global Styles\n\nApply 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.\n\n```yaml\nplugins:\n  - kroki:\n      styles:\n        box:\n          fill: \"#e6f3ff\"\n          stroke: \"#0066cc\"\n        actor:\n          fill: \"#ffe0b2\"\n          stroke: \"#bf360c\"\n        note:\n          fill: \"#ffffcc\"\n          stroke: \"#999900\"\n          color: \"#666600\"\n        package:\n          fill: \"#fff3e0\"\n          stroke: \"#e65100\"\n          color: \"#bf360c\"\n        text:\n          fill: \"#333333\"\n          font-family: \"Arial\"\n          font-size: \"14\"\n        line:\n          stroke: \"#666\"\n          font-color: \"#ff0000\"\n          font-family: \"Arial\"\n          label-background: \"#ffffff\"\n        background:\n          fill: \"#fff\"\n```\n\nThe `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).\n\nThe `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.\n\nTo skip style injection on a specific code block, use `no-style-inject=true`:\n\n````markdown\n```kroki-mermaid no-style-inject=true\ngraph LR\n    A[Unstyled] --\u003e B[Diagram]\n```\n````\n\n#### Support Matrix\n\n| **Style**                   | PlantUML | C4 PlantUML | Mermaid | GraphViz | BlockDiag\\* | Nomnoml | D2 | Structurizr |\n|-----------------------------|----------|-------------|---------|----------|-------------|---------|----|-------------|\n| **`box.fill`**              | ✅        | ✅           | ✅       | ✅        | ✅           | ✅       | ✅  | ✅           |\n| **`box.stroke`**            | ✅        | ✅           | ✅       | ✅        | ❌           | ✅       | ✅  | ✅           |\n| **`actor.fill`**            | ✅        | ✅           | ✅       | ❌        | ❌           | ❌       | ❌  | ✅           |\n| **`actor.stroke`**          | ✅        | ✅           | ✅       | ❌        | ❌           | ❌       | ❌  | ✅           |\n| **`note.fill`**             | ✅        | ✅           | ✅       | ❌        | ❌           | ❌       | ❌  | ❌           |\n| **`note.stroke`**           | ✅        | ✅           | ✅       | ❌        | ❌           | ❌       | ❌  | ❌           |\n| **`note.color`**            | ✅        | ✅           | ✅       | ❌        | ❌           | ❌       | ❌  | ❌           |\n| **`package.fill`**          | ✅        | ✅           | ❌       | ❌        | ❌           | ❌       | ❌  | ❌           |\n| **`package.stroke`**        | ✅        | ✅           | ❌       | ❌        | ❌           | ❌       | ❌  | ❌           |\n| **`package.color`**         | ✅        | ✅           | ❌       | ❌        | ❌           | ❌       | ❌  | ❌           |\n| **`text.fill`**             | ✅        | ✅           | ✅       | ✅        | ✅           | ❌       | ✅  | ✅           |\n| **`text.font-family`**      | ✅        | ✅           | ❌       | ✅        | ❌           | ✅       | ❌  | ❌           |\n| **`text.font-size`**        | ✅        | ✅           | ❌       | ❌        | ✅           | ✅       | ✅  | ✅           |\n| **`line.stroke`**           | ✅        | ✅           | ✅       | ✅        | ✅           | ❌       | ✅  | ✅           |\n| **`line.font-color`**       | ❌        | ❌           | ❌       | ✅        | ❌           | ❌       | ✅  | ❌           |\n| **`line.font-family`**      | ❌        | ❌           | ❌       | ✅        | ❌           | ❌       | ❌  | ❌           |\n| **`line.label-background`** | ❌        | ❌           | ✅       | ❌        | ❌           | ❌       | ❌  | ❌           |\n| **`background.fill`**       | ✅        | ✅           | ✅       | ✅        | ❌           | ✅       | ✅  | ❌           |\n\n\\*BlockDiag includes: blockdiag, seqdiag, actdiag, nwdiag, packetdiag, rackdiag.\n\nDiagram 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.\n\n### Theme-Aware Styles\n\nWhen 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.\n\n```yaml\nplugins:\n  - kroki:\n      styles_light:\n        box:\n          fill: \"#e8f4fd\"\n          stroke: \"#0066cc\"\n        text:\n          fill: \"#24292e\"\n        background:\n          fill: \"#ffffff\"\n      styles_dark:\n        box:\n          fill: \"#1a2a3a\"\n          stroke: \"#4da6ff\"\n        text:\n          fill: \"#e0e0e0\"\n        background:\n          fill: \"#1e1e1e\"\n```\n\nThe plugin renders **two versions** of each diagram — one with light styles, one with dark — and emits two `\u003cimg\u003e` tags using [MkDocs Material's light/dark image feature](https://squidfunk.github.io/mkdocs-material/reference/images/#light-and-dark-mode):\n\n```html\n\u003cimg alt=\"Kroki\" src=\"diagram-light.svg#only-light\" /\u003e\n\u003cimg alt=\"Kroki\" src=\"diagram-dark.svg#only-dark\" /\u003e\n```\n\nMaterial's CSS then shows the correct image based on the active color scheme.\n\n**Notes:**\n\n- Requires **MkDocs Material** theme — the `#only-light`/`#only-dark` mechanism is Material-specific\n- Requires `tag_format: img` (the default). `object` and `svg` formats fall back to light-mode styles only with a warning\n- Requires `http_method: POST` (images must be downloaded to use this feature)\n- `styles_light`/`styles_dark` take precedence over `styles` when set; using all three simultaneously logs a warning\n- The `no-style-inject=true` per-diagram option skips injection for both light and dark\n- Supports the same style properties and diagram types as the single `styles` config (see [Support Matrix](#support-matrix))\n\n## Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin)](https://github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin/graphs/contributors)\n\n\u003e Want to appear in the list of contributors?\n\u003e\n\u003e Get started by reading the [Contribution Guidelines](./CONTRIBUTING.md)\n\n## See Also\n\nDiagram examples can be found [here](https://kroki.io/examples.html).\n\nMore information about installing a self-manged Kroki-Service [here](https://docs.kroki.io/kroki/setup/install/).\n\nMore Plugins for MkDocs can be found [here](http://www.mkdocs.org/user-guide/plugins/)\n\n## Pre-Release-Versions\n\nInstall the newest pre-release version using pip:\n\n`pip install -i https://test.pypi.org/simple/ mkdocs-kroki-plugin`\n\n## Development\n\n### Setup\n\n```sh\ngit clone git@github.com:AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin.git\ncd mkdocs-kroki-plugin\nuv sync\n```\n\n### Pre-commit Hooks\n\nInstall the pre-commit hooks to run linting, type checking, and tests automatically on commit:\n\n```sh\nuv run pre-commit install\n```\n\nTo run all hooks manually:\n\n```sh\nuv run pre-commit run --all-files\n```\n\n### Testing\n\nRun tests:\n\n```sh\nuv run pytest\n```\n\nRun tests with coverage:\n\n```sh\nuv run pytest --cov\n```\n\n### Linting \u0026 Formatting\n\nRun ruff for linting and formatting:\n\n```sh\nuv run ruff check .\nuv run ruff format .\n```\n\n### Type Checking\n\nRun mypy:\n\n```sh\nuv run --group types mypy kroki\n```\n\n### Preview playground using mkdocs\n\n```\nuv run task playground:mkdocs\n```\n\n### Preview playground using techdocs-cli\n\n```\nuv run task playground:techdocs\n```\n\n### Creating a Release\n\nUse the release script to create a new version:\n\n```sh\n./release.py \u003cversion\u003e\n```\n\nFor example:\n\n```sh\n./release.py 1.2.3\n```\n\nThe script will:\n1. Validate the version format (semantic versioning: X.Y.Z)\n2. Check that the working tree is clean\n3. Update the `__version__` in `kroki/__init__.py`\n4. Create a commit: `chore: Bump version to X.Y.Z`\n5. Create an annotated git tag: `vX.Y.Z`\n6. Push the commit and tag to GitHub\n7. Open your browser to create a GitHub release where you can add the changelog\n\n**Requirements:**\n- Clean working tree (no uncommitted changes)\n- Version must follow semantic versioning format (e.g., 1.2.3)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Favateam-it-systemhaus%2Fmkdocs-kroki-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Favateam-it-systemhaus%2Fmkdocs-kroki-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Favateam-it-systemhaus%2Fmkdocs-kroki-plugin/lists"}