Insert clickable SVG image into Sphinx documentation

Question

I have SVG image file with several nodes each is associated with URL. If I open this file directly in browser I can click on each node and it will open different URLs. However when I use this picture in my Sphinx documentation it doesn't work - picture rendered as a whole so I need to open it by View Image and only then I can click on nodes.

I'm using standard image directive:

.. image:: myfile.svg

Probably I need to use something else?

Slipnoose

There is a similar issue in the graphviz extension. I guess this issue may be in Docutils, which is the foundation on which Sphinx is built. – Durand

I don't think this is a bug---using different ways to embed svg has different issues. See here. You can ask on Docutils mailing list for some hep and possibly request this feature, or you may write a sphinx extension to include svg images in the way you want. – Durand

Did you find a solution to this? – Squarely

With the repository version of Docutils, you can use the :loading: embed option for the image directive (see docutils.sourceforge.io/test/functional/expected/…). – Narrate

Answer 1

Sphinx generates <img> tags for images, which makes sense in most cases. However, to have the links inside the svg be clickable, you should use an <object> tag, i.e.:

.. raw:: html

    <object data="myfile.svg" type="image/svg+xml"></object>

(Regarding the GitHub issue you linked to, I don't think there's a lot that Sphinx can do here—it's really quite complicated—short of introducing a new option to the .. image directive that lets the user specify whether to render as an img or object tag.)

Brenn

@ruslo I think the sphinx maintainers took your bug report to mean that you're proposing to render all .. image svgs as an object tag. And that may break some other image options like :width and :height. But if you just write your own raw HTML that doesn't concern you. – Brenn

Answer 2

One simple solution would be to add a link to the svg file in this .. image:: myfile.svg command:

.. image:: myfile.svg
   :target: _images/myfile.svg

Take care of checking the relative directory where the images are copied when the html files are generated. By default, it should be _images/.

This way, you can click the SVG file, to see it in a plain page, and then click on it as usual (not a perfect solution but still..).

Ballista

@ruslo I think adding a target like this helps because the reflex for neophyte user is to click on an image, not Right Click → View Image. – Mcgaw

Answer 3

I am probably misunderstanding the OP's requirements, but why not just include the SVG into the sphinx documentation as html? This appears to work for me:

.. raw:: html
    :file: images/image.svg

Asben

This answer works for me. I had trouble to make the accepted answer work. I am using Sphinx Version: 4.0.1 – Autoeroticism

Answer 4

To include clickable svg links within sphinx I did the following:

.. raw:: html
    :file: ../graphs/pymedphys_analysis.gamma.svg

See:

https://raw.githubusercontent.com/pymedphys/pymedphys/1915b9496e93782bdac7dcebff7e26e470e5ff57/docs/graphs/graphs.rst

This then freed me to write the following within an imported style sheet:

svg {
    width: 100%;
}

https://github.com/pymedphys/pymedphys/blob/f4d404fa1cf3f551c4aa80ef27438f418c61a436/docs/_static/style.css

This made the svg fit the container as desired.

See:

https://pymedphys.com/developer/dependencies.html#pymedphys

Lafreniere

Answer 5

I like this way

.. raw:: html

    <a href="https://www.google.com/">
        <img src="https://img.shields.io/static/v1?&style=plastic&logo=appveyor&label=Google&message=link2google&color=FF0000" alt="No message"/></a>

---

What's the difference between <img> and <image>?

• <img>: standard HTML element

  The tag is a standard HTML element used to embed images into web pages.

  It supports various attributes such as src (to specify the image source), alt (alternative text for the image), width, and height.

  It's widely supported across all web browsers and is the correct way to display images in HTML documents.

• <image> reST syntax

  The is part of the reStructuredText (reST) syntax, which is a markup language used primarily in Python documentation.

  In reStructuredText, the directive .. image:: is used to include images in the document.

• svg element: <image>: The HTML spec defines as a synonym for while parsing HTML. This specific element and its behavior only apply inside SVG documents or inline SVGs.

Since I used ..raw:: html, it's probably better to stick to standard HTML for writing.

If you don't see any difference in the browser, it might be because the browser is trying to guess what the tags are.

Amplexicaul

What is the difference to using an "image" directive with "alt" and "target" options? – Narrate

@G.Milde Check out my updated: What's the difference between <img> and <image> – Amplexicaul

But why do you use raw HTML in the first place to get something that can be easily achieved with rST syntax? (Using "raw" HTML is required for direct embedding of SVG images or referencing SVG as <object> elements, but not to get an <img> element in HTML.) – Narrate

<image> is not reST syntax. As you correctly state below, the reST syntax is .. image::``. However, the <image>` tag is valid in HTML inside an <svg> element, as it is SVG syntax. – Narrate

The power of raw lies in its ability to directly write HTML content, eliminating the need to look up Sphinx-related syntax, packages, or implement it yourself. Of course, this is subjective, and the choice of which method to use still depends on personal or team preference. – Amplexicaul

Answer 6

I'm still looking for a better solution myself, but I ran into the same problem and used this workaround.

You can use the download directive to give the user a link to the file.

:download:`svg <images/image.svg>`

Squarely