https://github.com/bertpl/mkdocs-gitsvg

MkDocs plugin that renders gitsvg git-graph diagrams from fenced code blocks to inline SVG
https://github.com/bertpl/mkdocs-gitsvg

Last synced: 7 days ago
JSON representation

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

• Host: GitHub
• URL: https://github.com/bertpl/mkdocs-gitsvg
• Owner: bertpl
• License: mit
• Created: 2026-06-03T10:21:02.000Z (14 days ago)
• Default Branch: main
• Last Pushed: 2026-06-03T10:25:13.000Z (14 days ago)
• Last Synced: 2026-06-03T12:13:30.016Z (14 days ago)
• Language: Python
• Size: 61.5 KB
• Stars: 0
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# mkdocs-gitsvg

MkDocs plugin that renders [gitsvg](https://github.com/bertpl/gitsvg) git-graph

diagrams from fenced code blocks to inline SVG at build time.

[![CI](https://img.shields.io/github/actions/workflow/status/bertpl/mkdocs-gitsvg/push_to_main.yml?branch=main&label=CI)](https://github.com/bertpl/mkdocs-gitsvg/actions/workflows/push_to_main.yml)

[![PyPI](https://img.shields.io/pypi/v/mkdocs-gitsvg.svg)](https://pypi.org/project/mkdocs-gitsvg/)

[![Python](https://img.shields.io/pypi/pyversions/mkdocs-gitsvg.svg)](https://pypi.org/project/mkdocs-gitsvg/)

[![License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/bertpl/mkdocs-gitsvg/blob/main/LICENSE)

No client-side JavaScript: diagrams are rendered server-side at build time, so

they work in any browser and in offline / PDF exports.

## Installation

```bash

pip install mkdocs-gitsvg

```

## Usage

Enable the plugin in `mkdocs.yml`:

```yaml

plugins:

  - gitsvg

```

Then draw a git graph in any page with a ` ```gitsvg ` fenced block whose body

is a [gitsvg](https://github.com/bertpl/gitsvg) JSONL op-stream:

````markdown

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

```yaml

plugins:

  - gitsvg:

      fence_name: gitsvg          # fenced-block language tag to intercept

      css_class: gitsvg-diagram   # class on the wrapper 


      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](https://github.com/bertpl/mkdocs-gitsvg) for the full

reference.

## License

MIT — see [LICENSE](LICENSE).