{"id":9116,"library":"mkdocs-kroki-plugin","title":"MkDocs Kroki Plugin","description":"mkdocs-kroki-plugin is an MkDocs plugin designed to embed Kroki-Diagrams directly into your documentation. It is currently at version 1.6.0 and maintains an active development cycle, releasing new features, bug fixes, and improvements frequently, as seen in its recent series of minor and patch releases.","status":"active","version":"1.6.0","language":"en","source_language":"en","source_url":"https://github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin","tags":["mkdocs","diagrams","kroki","documentation","static-site-generator"],"install":[{"cmd":"pip install mkdocs-kroki-plugin","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Core dependency for MkDocs plugin functionality.","package":"mkdocs","optional":false},{"reason":"Used for making HTTP requests to the Kroki server.","package":"httpx","optional":false},{"reason":"Likely used for functional programming patterns and error handling.","package":"result","optional":false},{"reason":"For safely parsing XML, potentially for SVG output from Kroki.","package":"defusedxml","optional":false}],"imports":[{"symbol":"KrokiPlugin","correct":"from kroki.plugin import KrokiPlugin"}],"quickstart":{"code":"# mkdocs.yml\nsite_name: My Docs with Kroki\n\nplugins:\n  - kroki:\n      server_url: https://kroki.io # Optional, default is https://kroki.io\n\n# docs/index.md\n# Example BlockDiag diagram\n```kroki-blockdiag\nblockdiag {\n  blockdiag -> generates -> \"block-diagrams\";\n  blockdiag -> is -> \"very easy!\";\n  blockdiag [color = \"greenyellow\"];\n  \"block-diagrams\" [color = \"pink\"];\n  \"very easy!\" [color = \"orange\"];\n}\n```\n\n# To run:\n# mkdocs serve","lang":"yaml","description":"Add `kroki` to your `mkdocs.yml` plugins section and use fenced code blocks with `kroki-<diagram_type>` to embed diagrams in your Markdown files."},"warnings":[{"fix":"Update your `mkdocs.yml` configuration to use `snake_case` for options and remove any deprecated settings. Refer to the plugin's README for the latest configuration schema.","message":"Configuration options were renamed and deprecated options removed in v1.0.0 to align with MkDocs conventions. For example, `ServerURL` became `server_url`, and options like `Enablebpmn` or `DownloadImages` were removed.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Evaluate ProperDocs as a potential long-term solution for your documentation setup if you encounter complex upgrade paths or specific feature needs not met by vanilla MkDocs and its plugins.","message":"The plugin's documentation suggests considering migration to ProperDocs, a fork of MkDocs, which may simplify future updates.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure `http_method` is set to `POST` and `tag_format` is `img` in your plugin configuration when using `styles_light` or `styles_dark` for optimal theme integration.","message":"Theme-aware styles (`styles_light`, `styles_dark`) for diagrams require `http_method: POST` and `tag_format: img` to function correctly, particularly with themes like Material for MkDocs. Other `tag_format` settings (`object`, `svg`) will fall back to light-mode styles only with a warning.","severity":"gotcha","affected_versions":">=1.5.0"},{"fix":"Upgrade to `mkdocs-kroki-plugin` version 1.6.0 or newer to ensure all diagrams are correctly parsed and rendered, even when preceded by code blocks with unusual attributes.","message":"Older versions (prior to v1.6.0) might incorrectly skip diagrams that appear after code blocks with unrecognized attributes due to a fence regex issue.","severity":"gotcha","affected_versions":"<1.6.0"},{"fix":"Change the default port for either your local Kroki Docker instance or `mkdocs serve` (e.g., `mkdocs serve -a 0.0.0.0:8001`). Configure `server_url` in `mkdocs.yml` to point to the correct Kroki server address.","message":"When running a local Kroki server via Docker, its default port (often 8000) can conflict with `mkdocs serve`'s default port, leading to startup issues.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Upgrade `mkdocs-kroki-plugin` to the latest version. If using `mkdocs-techdocs-core`, ensure it's also updated. Check for configuration regarding `tag_format` (default `img` is usually more compatible than `object` or `svg` in some environments) and `http_method: POST` for downloading images.","cause":"Specific issues with how Backstage TechDocs handles local asset paths or `object` tags generated by the plugin in older versions. For example, `0.8.1` switched to `<object>` tags which caused problems for Backstage.","error":"Broken images or missing diagrams in Backstage TechDocs site after upgrade."},{"fix":"Verify the plugin is correctly listed under `plugins:` in `mkdocs.yml`. Check that your diagram syntax is valid for the specified Kroki type. Ensure the `server_url` is correct and reachable (default is `https://kroki.io`). Upgrade to the latest plugin version to address parsing fixes.","cause":"Incorrect plugin activation in `mkdocs.yml`, a non-reachable Kroki server, syntax errors in the diagram code, or a regex parsing issue in older versions.","error":"Diagrams are not displayed at all, just showing the code fence."},{"fix":"Update your `mkdocs.yml` to use the new snake_case configuration keys (e.g., `server_url` instead of `ServerURL`) and remove any deprecated configuration options. Refer to the plugin's documentation for the updated config schema.","cause":"This typically occurs after upgrading to v1.0.0 where configuration option names changed from PascalCase to snake_case and some options were removed.","error":"MkDocs build fails with 'KeyError' or 'TypeError' related to plugin configuration after update."},{"fix":"Increase the `request_timeout` option in your `mkdocs.yml` plugin configuration (e.g., `request_timeout: 60`). `server_url: !ENV [KROKI_SERVER_URL, 'https://kroki.io']`","cause":"The default HTTP request timeout to the Kroki server might not be sufficient for complex or large diagrams that take longer to process.","error":"HTTP timeout errors when rendering large diagrams."}]}