{"id":21575,"library":"mkdocs-drawio","title":"MkDocs Draw.io Plugin","description":"MkDocs plugin for embedding Draw.io (diagrams.net) diagrams in your documentation. It supports .drawio, .dio, and .drawio.svg files, with features like dark mode, custom toolbars, and page navigation. Current version: 1.15.0, actively maintained with regular releases.","status":"active","version":"1.15.0","language":"python","source_language":"en","source_url":"https://github.com/tuunit/mkdocs-drawio","tags":["mkdocs","plugin","drawio","diagrams"],"install":[{"cmd":"pip install mkdocs-drawio","lang":"bash","label":"Install via pip"}],"dependencies":[{"reason":"Required plugin framework","package":"mkdocs","optional":false},{"reason":"XML/SVG parsing for diagram files","package":"lxml","optional":false}],"imports":[{"note":"This is a MkDocs plugin, not a Python module to import directly. It is configured in mkdocs.yml.","wrong":"import mkdocs_drawio","symbol":"mkdocs_drawio","correct":"mkdocs_drawio (imported automatically as MkDocs plugin)"}],"quickstart":{"code":"# mkdocs.yml\nplugins:\n  - drawio\n","lang":"yaml","description":"Add the drawio plugin to your MkDocs configuration. Then place .drawio files in your docs directory and reference them with standard Markdown image syntax like `![Diagram](diagram.drawio)`."},"warnings":[{"fix":"Update to mkdocs-drawio >= 1.12.0.","message":"MkDocs 1.6+ has breaking changes in plugin APIs; older versions of mkdocs-drawio may not work. Upgrade to at least v1.12.0 for MkDocs 1.6 support.","severity":"breaking","affected_versions":"<1.12.0"},{"fix":"Move .drawio files into your docs folder (or a subfolder).","message":"Diagram files must be placed inside the docs directory. Files outside will not be processed.","severity":"gotcha","affected_versions":"all"},{"fix":"Use `plugins: [drawio]` instead of `plugins: [drawio-file]`.","message":"The old `drawio-file` configuration key is deprecated in favor of `drawio` in mkdocs.yml.","severity":"deprecated","affected_versions":"<1.0.0"},{"fix":"Add `dark_mode: true` under the drawio plugin configuration in mkdocs.yml.","message":"Dark mode requires the drawio toolbox to have the 'dark mode' option enabled. It does not automatically match the browser/system theme.","severity":"gotcha","affected_versions":">=1.11.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Run `pip install mkdocs-drawio` and ensure the Python environment is active.","cause":"mkdocs-drawio pip package not installed in the environment.","error":"ERROR  -  Config value: 'plugins'. Error: The \"drawio\" plugin is not installed."},{"fix":"In mkdocs.yml, change `plugins: [drawio-file]` to `plugins: [drawio]`.","cause":"Using the old plugin name 'drawio-file' instead of 'drawio'.","error":"ValueError: Unrecognised configuration key: 'drawio-file'"},{"fix":"Verify the .drawio file exists inside the docs folder and the Markdown image path is relative to the docs root (e.g., `![Diagram](images/diagram.drawio)`).","cause":"Diagram file not found in the docs directory or path is incorrect.","error":"FileNotFoundError: [Errno 2] No such file: 'diagram.drawio'"},{"fix":"Re-save the diagram from Draw.io to ensure proper XML format.","cause":"The .drawio file is corrupted or not a valid XML.","error":"lxml.etree.XMLSyntaxError: ..."}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}