{"id":24041,"library":"mkdocs-diagrams","title":"MkDocs Diagrams","description":"A MkDocs plugin that renders diagrams defined using the Diagrams library (Python DSL for cloud system architecture diagrams) inline in your documentation. The plugin hooks into the MkDocs build process, compiling .py diagram scripts into SVG or PNG images. Current version 1.0.0, stable but maintained with low release cadence.","status":"active","version":"1.0.0","language":"python","source_language":"en","source_url":"https://github.com/zoni/mkdocs-diagrams","tags":["mkdocs","diagrams","plugin","diagram-as-code","cloud architecture"],"install":[{"cmd":"pip install mkdocs-diagrams","lang":"bash","label":"Install"}],"dependencies":[{"reason":"Required to compile diagram scripts","package":"diagrams","optional":false},{"reason":"Plugin host framework","package":"mkdocs","optional":false}],"imports":[{"note":"Common mistake – DiagramsPlugin is exposed at package level, not in a submodule","wrong":"from mkdocs_diagrams.plugin import DiagramsPlugin","symbol":"DiagramsPlugin","correct":"from mkdocs_diagrams import DiagramsPlugin"}],"quickstart":{"code":"import os\nfrom mkdocs.config.base import Config\nfrom mkdocs_diagrams import DiagramsPlugin\n\n# Minimal config simulation\nconfig = Config(\n    plugins={\n        'diagrams': DiagramsPlugin()\n    }\n)\n# In real use: add 'diagrams' to mkdocs.yml plugins list\nprint(\"Plugin configured successfully\")","lang":"python","description":"Initialize the plugin in your MkDocs project. Add 'diagrams' to the plugins list in mkdocs.yml, then place .py diagram scripts in your docs directory."},"warnings":[{"fix":"Ensure graphviz executable is installed on the system (e.g., apt-get install graphviz) and all imports are available.","message":"Diagram script must be valid Python and produce a diagram object. If the script fails (e.g., missing dependencies like graphviz) the MkDocs build will break.","severity":"gotcha","affected_versions":"all"},{"fix":"Each diagram script must include a `with Diagram(...):` block and the corresponding output.","message":"The plugin only processes .py files that contain a diagram generation call. Files without a diagram definition will raise an error or produce empty output.","severity":"gotcha","affected_versions":"all"},{"fix":"Use Python 3.7+.","message":"Python 3.6 support was dropped in version 1.0.0; package metadata now requires python>=3.7.","severity":"deprecated","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"pip install diagrams","cause":"The 'diagrams' library is not installed. It is a required dependency.","error":"ModuleNotFoundError: No module named 'diagrams'"},{"fix":"Install graphviz on your system: apt-get install graphviz (Linux) or brew install graphviz (macOS) or download from graphviz.org.","cause":"Graphviz command 'dot' not found in PATH. The diagrams library requires graphviz executables.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'dot'"},{"fix":"Ensure your script includes `with Diagram(\"title\"):` and appropriate nodes/edges.","cause":"The Python script did not create a diagram with the `Diagram` context manager.","error":"Exception: Diagram script ... did not produce any output"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}