Metadata-Version: 2.4
Name: mkdocs-graphviz
Version: 2.0.1
Summary: Modern MkDocs plugin for Graphviz with scoped configuration and native light/dark rendering
Author-email: Rodrigo Schwencke <rod2ik.dev@gmail.com>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://rod2ik.gitlab.io/mkdocs-graphviz/
Project-URL: Documentation, https://rod2ik.gitlab.io/mkdocs-graphviz/
Project-URL: Repository, https://gitlab.com/rod2ik/mkdocs-graphviz
Project-URL: Issues, https://gitlab.com/rod2ik/mkdocs-graphviz/-/issues
Keywords: mkdocs,markdown,graphviz,dot,svg,documentation,education
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: MkDocs
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Documentation
Classifier: Topic :: Text Processing :: Markup
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mkdocs<2.0,>=1.4
Requires-Dist: Markdown>=3.4
Requires-Dist: PyYAML>=6.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: mkdocs<2.0,>=1.4; extra == "dev"
Requires-Dist: mkdocs-material<10,>=9; extra == "dev"
Requires-Dist: pymdown-extensions<11,>=10; extra == "dev"
Requires-Dist: pytest<10,>=7; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: twine>=6; extra == "dev"
Dynamic: license-file

# 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:

```bash
python -m pip install mkdocs-graphviz
```

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

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

## Minimal MkDocs configuration

```yaml
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:

```yaml
light:
  node:
    color: "#000000"
```

## Markdown syntax

The default fence is intentionally simple:

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

Fence words are data-driven aliases:

```yaml
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:

```text
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:

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

### Per graph

A Graphviz fence may start with its own YAML header:

````markdown
```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:

```text
{{ 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.

```yaml
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:

```yaml
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:

```bash
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:

```javascript
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

```bash
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`.
