mkdocs-graphviz

mkdocs-graphviz renders Graphviz/DOT source to inline SVG at MkDocs build time.

Version 2.0.1 is a deliberately breaking redesign. It is a real MkDocs plugin, ships its own JavaScript/CSS runtime inside the Python wheel, supports native Light/Dark Graphviz rendering, and exposes Graphviz attributes without legacy shortcuts.

Installation

Install Graphviz with your operating system package manager, then install the plugin:

python -m pip install mkdocs-graphviz

For local development on an Arch Linux system using the system Python:

python -m pip install --break-system-packages -e .

Minimal MkDocs configuration

plugins:
  - search
  - mkdocs_graphviz:
      common:
        graph:
          bgcolor: "none"
      light:
        node:
          color: "#000000"
          fontcolor: "#000000"
        edge:
          color: "#000000"
          fontcolor: "#000000"
      dark:
        node:
          color: "#FFFFFF"
          fontcolor: "#FFFFFF"
        edge:
          color: "#FFFFFF"
          fontcolor: "#FFFFFF"

No extra_javascript, extra_css, CDN, or Markdown extension entry is required. The plugin injects its packaged minified runtime assets automatically.

There are no scope-less shortcuts in 2.0. Every native Graphviz attribute belongs explicitly to graph, node, or edge inside common, light, or dark.

Hex colors use Graphviz syntax and therefore keep the leading #. Quote them in YAML:

light:
  node:
    color: "#000000"

Markdown syntax

The default fence is intentionally simple:

```dot
digraph G {
    A -> B -> C
}
```

Fence words are data-driven aliases:

plugins:
  - mkdocs_graphviz:
      fences:
        dot: dot
        gv: dot
        neato: neato
        radial: twopi

The key is the Markdown fence word; the value is the Graphviz layout passed to dot -K....

Configuration inheritance

The effective configuration is resolved independently for Light and Dark:

Graphviz built-in defaults
        ↓
global common.graph/node/edge
        ↓
global light|dark.graph/node/edge
        ↓
page common.graph/node/edge
        ↓
page light|dark.graph/node/edge
        ↓
graph common.graph/node/edge
        ↓
graph light|dark.graph/node/edge
        ↓
explicit attributes in DOT source

Per-page

Use normal MkDocs YAML front matter:

---
graphviz:
  common:
    graph:
      rankdir: LR
  dark:
    node:
      color: "#FFFFFF"
---

Per graph

A Graphviz fence may start with its own YAML header:

```dot
---
common:
  graph:
    rankdir: LR
light:
  node:
    color: "#0055AA"
dark:
  node:
    color: "#88CCFF"
---
digraph G {
    A -> B
}
```

The header is consumed by mkdocs-graphviz and is never sent to Graphviz.

External .dot files

Keep a graph in a separate file under docs_dir and render it with:

{{ graphviz("../graphs/example.dot") }}

Relative paths are resolved from the current Markdown page. A path beginning with / is resolved from docs_dir. Imports may not escape docs_dir. Imported .dot files may use the same optional per-graph YAML header.

Generic Graphviz attributes

mkdocs-graphviz does not hard-code one Python option per Graphviz attribute. Entries under graph, node, and edge are translated generically to Graphviz -G, -N, and -E default attributes.

common:
  graph:
    rankdir: LR
    splines: ortho
    nodesep: 0.5
  node:
    shape: box
    style: rounded
    penwidth: 1.5
  edge:
    arrowhead: diamond
    arrowsize: 0.8

The bundled offline schema is used only for diagnostics:

validation: warn   # off | warn | strict

warn is the default. Unknown or wrong-scope attributes produce a build warning but are still passed unchanged to Graphviz. strict turns them into build errors. off performs no schema validation.

Refresh the bundled schema deliberately with:

yarn schema:update

yarn bfc runs the offline yarn schema:check; it intentionally does not perform a network update.

Light/Dark architecture

If the effective Light and Dark configurations are identical, the graph is rendered once. If they differ, Graphviz renders two independent SVGs at build time. The tiny bundled browser runtime only selects the correct already-rendered variant. This permits theme-specific attributes that alter layout, shape, dimensions, fonts, or any other Graphviz behavior; it does not rely on recoloring an SVG after the fact.

The runtime exposes:

window.MkDocsGraphviz.refresh(root)
window.MkDocsGraphviz.setTheme(root, "light")
window.MkDocsGraphviz.setTheme(root, "dark")
window.MkDocsGraphviz.setTheme(root, "auto")

It is designed to tolerate dynamic DOM insertion and hidden/revealed content and includes an optional adapter registration for mkdocs-revealjs without introducing a hard dependency on RevealJS.

Development workflow

yarn dev
yarn dev:lan
yarn build
yarn build:python
yarn build:docs
yarn build:full
yarn build:full:check
yarn bfc
yarn zip

package.json is the single source of truth for the project version. yarn version:sync generates src/mkdocs_graphviz/_version.py.

yarn dev keeps the project installed in Python editable mode, so other MkDocs projects can use the current local source without reinstalling after each change.

Compatibility target

The HTML/runtime architecture is designed for ordinary MkDocs pages and nested/dynamic content such as admonitions, Content Tabs, mkdocs-maths-admonitions, mkdocs-xtables, mkdocs-superquiz, and mkdocs-revealjs. Integration tests cover the generic nesting behavior; project-specific compatibility can be extended without coupling the Graphviz renderer to those plugins.

License

GNU GPL v3 or later. See LICENSE.