Metadata-Version: 2.4
Name: sphinx-gp-mermaid
Version: 0.0.1a33
Summary: Build-time Mermaid diagrams for Sphinx — dual light/dark inline SVG rendered via mermaid-cli
Project-URL: Repository, https://github.com/git-pull/gp-sphinx
Author-email: Tony Narlock <tony@git-pull.com>
License: MIT
Keywords: diagrams,documentation,mermaid,sphinx,svg
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Sphinx
Classifier: Framework :: Sphinx :: Extension
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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 :: Documentation :: Sphinx
Classifier: Typing :: Typed
Requires-Python: <4.0,>=3.10
Requires-Dist: sphinx>=8.1
Description-Content-Type: text/markdown

# sphinx-gp-mermaid

Build-time Mermaid diagrams for Sphinx. Fenced `mermaid` blocks render to
inline `<svg>` during the build via `mmdc`
([@mermaid-js/mermaid-cli](https://github.com/mermaid-js/mermaid-cli)):
no client-side mermaid runtime, no asynchronous pop-in, no layout shift.

Each diagram is rendered twice — a light and a dark variant — and both are
inlined, toggled by CSS on `body[data-theme]`. Diagrams paint with the page,
follow the theme toggle without JavaScript, and survive SPA navigation as
live DOM.

## Install

```console
$ pip install sphinx-gp-mermaid
```

## Usage

Enable the extension in `conf.py`:

```python
extensions = ["sphinx_gp_mermaid"]
```

With gp-sphinx, opt in via `merge_sphinx_config`:

```python
config = merge_sphinx_config(
    extra_extensions=["sphinx_gp_mermaid"],
)
```

Author diagrams as MyST fences:

````markdown
:::{mermaid}
:caption: How it flows.
:alt: a request flowing through two steps
:name: request-flow
:responsive: fit

flowchart LR
    a --> b
:::
````

`fit` is the default responsive policy: the rendered SVG scales down to the
content column. Use `:responsive: preserve` when a dense diagram should keep
its intrinsic width and scroll horizontally instead of shrinking labels.

## Renderer toolchain

Rendering shells out to `mmdc`, resolved from the `mermaid_cmd` config value,
then `<confdir>/node_modules/.bin/mmdc`, then `PATH`. Install it in the docs
toolchain:

```console
$ pnpm add -D @mermaid-js/mermaid-cli
```

When the renderer is unavailable the build still succeeds: diagrams degrade
to their source text with a single warning.

## Documentation

See the [full documentation](https://gp-sphinx.git-pull.com/packages/sphinx-gp-mermaid/)
for directive options, theming, caching, and CI setup.
