mkdocs-gitsvg

MkDocs plugin that renders gitsvg git-graph diagrams from fenced code blocks to inline SVG at build time.

No client-side JavaScript: diagrams are rendered server-side at build time, so they work in any browser and in offline / PDF exports.

Installation

pip install mkdocs-gitsvg

Usage

Enable the plugin in mkdocs.yml:

plugins:
  - gitsvg

Then draw a git graph in any page with a ```gitsvg fenced block whose body is a gitsvg JSONL op-stream:

```gitsvg
{"op": "branch", "name": "main", "label_side": "before"}
{"op": "commit", "branch": "main", "id": "c1", "msg": "initial commit", "hash": "auto"}
{"op": "commit", "branch": "main", "id": "c2", "msg": "add README", "hash": "auto"}
```

The block renders to an inline SVG git graph in the built site.

Configuration

The plugin needs no configuration. Available options (with defaults):

plugins:
  - gitsvg:
      fence_name: gitsvg          # fenced-block language tag to intercept
      css_class: gitsvg-diagram   # class on the wrapper <div>
      on_error: warn              # warn | raise | show

on_error controls what happens when a diagram fails to render: warn (default) shows an error box and logs a warning (so mkdocs build --strict fails), raise fails the build immediately, and show shows the box silently. A bundled stylesheet is linked automatically. See the documentation site for the full reference.

License

MIT — see LICENSE.