sphinx-inline-svg

≫日本語版

Overview

Sphinx extension to make SVG images inline.
It helps to make text in SVG into hyperlink.
If the builder is not html, it has no effect.

Installation

pip

pip install sphinx-inline-svg

rye

rye add --dev sphinx-inline-svg

Usage

conf.py

Add it to extensions.

# conf.py

extensions = [
    'sphinx_inline_svg',
]

Add CSS class

Add CSS class to SVG image to be inlined.

.. image:: img/chart.drawio.svg
    :class: inline-svg

As for MyST, enable attrs_inline in conf.py.

# conf.py

myst_enable_extensions = [
    "attrs_inline",
]

![](img/chart.drawio.svg){.inline-svg}

Define inline-svg class in CSS if actual style is needed.

/* _static/css/custom.css */

/* example */
.inline-svg {
  max-width: 100%;
  height: auto;
}

And add it in conf.py as follows.

# conf.py

def setup(app):
    app.add_css_file('css/custom.css')

[!NOTE] Even if you don't define actual style, giving the class will inline SVGs.

Hyperlink

To make text in SVG a hyperlink, for example, edit it as follows in draw.io.

Link notation

Link destination that is generated after build depends on Link notation.

[!NOTE] As for the last notation, generated destination is relative from the page where SVG is extracted to, not from the SVG itself.

Configuration

The following settings can be configured in conf.py. If you do not write the configuration itself, the default value is applied.

# conf.py

inline_svg_classes = ['inline-svg', 'selectable-svg']

[!NOTE] The svg element in SVG file saved by draw.io has "content" attribute, but this is data for editing by the draw.io app, so it is not necessary for the svg element to be inlined.

Known problems

It has been reported that inlining SVG images saved by Draw.io Integration extension of VSCode with sphinx-inline-svg results in garbled characters. 😥

In addition, hyperlinks in SVG images saved by Draw.io Integration may not become clickable. In such cases, inlining with sphinx-inline-svg does not make them clickable. 😥