MkDocs Diagrams

1.0.0 verified Fri May 01 auth: no python

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.

pip install mkdocs-diagrams

Common errors

error ModuleNotFoundError: No module named 'diagrams' ↓

cause The 'diagrams' library is not installed. It is a required dependency.

fix

pip install diagrams

error FileNotFoundError: [Errno 2] No such file or directory: 'dot' ↓

cause Graphviz command 'dot' not found in PATH. The diagrams library requires graphviz executables.

fix

Install graphviz on your system: apt-get install graphviz (Linux) or brew install graphviz (macOS) or download from graphviz.org.

error Exception: Diagram script ... did not produce any output ↓

cause The Python script did not create a diagram with the `Diagram` context manager.

fix

Ensure your script includes with Diagram("title"): and appropriate nodes/edges.

Warnings

gotcha 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. ↓

fix Ensure graphviz executable is installed on the system (e.g., apt-get install graphviz) and all imports are available.

gotcha 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. ↓

fix Each diagram script must include a `with Diagram(...):` block and the corresponding output.

deprecated Python 3.6 support was dropped in version 1.0.0; package metadata now requires python>=3.7. ↓

fix Use Python 3.7+.

Imports

DiagramsPlugin
wrong
```
from mkdocs_diagrams.plugin import DiagramsPlugin
```
correct
```
from mkdocs_diagrams import DiagramsPlugin
```
Common mistake – DiagramsPlugin is exposed at package level, not in a submodule

Quickstart

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.

import os
from mkdocs.config.base import Config
from mkdocs_diagrams import DiagramsPlugin

# Minimal config simulation
config = Config(
    plugins={
        'diagrams': DiagramsPlugin()
    }
)
# In real use: add 'diagrams' to mkdocs.yml plugins list
print("Plugin configured successfully")