DOC: Clarify SVG hyperlink behavior in gallery hyperlinks example by jayaprajapatii · Pull Request #31497 · matplotlib/matplotlib

jayaprajapatii · 2026-04-13T17:02:57Z

Summary

Show the generated SVG outputs in the hyperlinks example by embedding them directly in the documentation.

Problem

The example generated SVG files with hyperlinks, but they were not visible or interactive in the documentation, making the behavior unclear.

Solution

The example still generates SVG files as before.
The documentation now embeds these SVGs using HTML (<object>), so that the hyperlinks inside the SVG remain interactive.

Impact

Makes SVG outputs visible in the documentation
Preserves hyperlink interactivity (clickable elements)

timhoffm

This is not the intended solution for #31452

Instead, we want to show the SVG images. There are to possible approaches

the difficult one: make sphinx-gallery (optionally) support creating SVG output.
the hacked one: render the SVG image locally and add it as a static image to the example.

jayaprajapatii · 2026-04-13T19:40:50Z

@timhoffm Thanks for the clarification!

I understand that the goal is to actually show the SVG output rather than just explain the behavior. I’ll work on implementing the second approach by rendering the SVG locally and adding it as a static image to the example.

timhoffm

Missing svg files and inappropirate comment location/(maybe) content.

Please take more care in veryifing the result of your changes.

timhoffm · 2026-04-15T01:23:36Z

+# NOTE:
+# Hyperlinks in SVG output may not appear interactive in the documentation
+# because Sphinx renders SVGs as static images (<img> tags),
+# so hyperlinks are not clickable
+# The SVG images are shown below.
+# To see working hyperlinks, open the generated SVG file directly in a browser.
+


This renders as a comment in the code, which is not appropriate. Instead it should be regular example text.

Also, I'm not clear whether the content is correct. If we show the svgs here, is it still needed to open the files separately in a browser?

timhoffm

Again, I urge you to validate your proposals locally before pushing to a public PR. - Or at the very least mark your PR as draft until you are sure it does the right thing.

Posting half-baked PRs causes unnecessary reviewer effort. In the interest of project health, we can only tolerate so much of this. Continued deficits in PR quality may lead to closure.

timhoffm · 2026-04-15T10:41:49Z

+# %%
+# Display generated SVGs in docs
+#
+# .. image:: scatter.svg


The SVGs do not appear in the documentation. Likely because the generated .rst source file are in a different place than the .py. So the files cannot be found. See also https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#images

jayaprajapatii · 2026-04-15T11:27:02Z

@timhoffm Thank you for pointing this out, and sorry for not validating the changes properly before pushing.

I now understand the issue with SVGs not appearing due to incorrect paths. I'll fix this and verify the documentation locally before updating the PR.

jayaprajapatii · 2026-04-19T16:15:10Z

Hello @timhoffm
I’ve addressed the previous feedback.

Added the generated SVG files to doc/_static
Updated the example to correctly reference these SVG files
Verified locally using make html.

The outputs are now visible in the documentation.

Please let me know if anything still needs improvement.

timhoffm · 2026-04-21T12:48:18Z

I don't understand what's happening here. Can you explain this?

previously the example did not show any output
now it shows the images right below each example code. Why does this work? Does Sphinx gallery pick up the images you added? But the rendered result is png, not SVG? Does Sphinx convert the SVGs to png?
What does the extra section do?

Additionally, we want the SVGs embedded into the HTML, not PNGs as they don't expose the hyperlinks.

jayaprajapatii · 2026-04-26T16:00:21Z

Hello @timhoffm, I’ve updated the example based on your suggestion:

embedded the generated SVGs in the docs using <object> so the links are preserved

The elements are now clickable (cursor changes on hover), and clicking triggers navigation. However, the link opens within the embedded SVG (replacing the image).

Could you please confirm if this behavior is acceptable, or would you prefer the links to open externally (e.g., in a new tab)?

Happy to adjust accordingly.

direct html embedding seems like the way to go.

timhoffm · 2026-04-26T22:28:04Z

Opening externally would be better, if that is possible.

Could you please rebase onto main? Doc builds are failing, but it's not due to the changes in this PR. I suspect that the merge of this branch with main somehow messes up the doc build environment config.

jayaprajapatii · 2026-04-27T08:18:27Z

@timhoffm Thanks! I’ve rebased the branch onto main.

Regarding external opening: currently, the links are embedded in the SVG and clicking navigates within the SVG. Could you confirm if this is acceptable, or if you'd prefer a specific enforcing opening in a new tab?

timhoffm · 2026-04-27T08:39:04Z

Thanks for rebasing. This looks good now.

Opening externally is strongly preferred. I suspect the way to do this is adding a target="_blank" attribute to the SVG. From my understanding we should always do this as the https://matplotlib.org/stable/api/_as_gen/matplotlib.artist.Artist.set_url.html is intended for external links. This change would need to happen here, but should be done as a separate PR because this is a behavioral change (or I'd say fix) that we should discuss independently of the gallery update.

jayaprajapatii · 2026-04-27T09:15:48Z

Thanks for the clarification! @timhoffm

Understood, I'll keep this PR focused on the documentation update.

I’ll open a separate PR for adding target="_blank" to SVG links.

timhoffm

This is good, but I would like to postpone merging until we have the link target fixed: #31578

When embedding SVG in HTML, link `href`s can target different browsing contexts. This e.g. leads to links inside SVGs in matplotlib#31497 replacing the SVG image instead of opening a new browser window. The solution is to set `target="_blank"` for all links that implement `Artist.get_url()`. This is always intended as an external link, so universally adding `target="_blank"` is justified. Background info: https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Attribute/target https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Attribute/target#_blank

timhoffm

Please also rebase on main to pick up #31578

timhoffm · 2026-05-16T06:17:41Z

Thanks @jayaprajapatii !

QuLogic · 2026-05-16T06:35:32Z

@meeseeksdev backport to v3.11.x

…perlinks example

…497-on-v3.11.x Backport PR #31497 on branch v3.11.x (DOC: Clarify SVG hyperlink behavior in gallery hyperlinks example)

github-actions Bot added the Documentation: examples files in galleries/examples label Apr 13, 2026

timhoffm requested changes Apr 13, 2026

View reviewed changes

timhoffm previously requested changes Apr 15, 2026

View reviewed changes

timhoffm reviewed Apr 15, 2026

View reviewed changes

jayaprajapatii marked this pull request as draft April 15, 2026 11:28

Lankalapallikumar mentioned this pull request Apr 16, 2026

[Doc]: svg links example should show the svgs? #31452

Closed

jayaprajapatii marked this pull request as ready for review April 19, 2026 16:15

jayaprajapatii marked this pull request as draft April 23, 2026 15:05

jayaprajapatii force-pushed the fix-svg-hyperlink-doc branch from 336724d to 1cf8052 Compare April 26, 2026 16:23

jayaprajapatii marked this pull request as ready for review April 26, 2026 16:27

jayaprajapatii force-pushed the fix-svg-hyperlink-doc branch from 1cf8052 to 8d2302d Compare April 27, 2026 07:51

timhoffm mentioned this pull request Apr 28, 2026

FIX: URL links in SVG should have target='_blank' #31578

Merged

timhoffm approved these changes Apr 28, 2026

View reviewed changes

QuLogic reviewed Apr 28, 2026

View reviewed changes

Comment thread galleries/examples/misc/hyperlinks_sgskip.py Outdated

timhoffm mentioned this pull request May 11, 2026

DOC: Add thumbnail for hyperlinks_sgskip gallery example #31377

Closed

timhoffm reviewed May 12, 2026

View reviewed changes

Comment thread galleries/examples/misc/hyperlinks_sgskip.py

jayaprajapatii marked this pull request as draft May 14, 2026 06:20

Enable SVG hyperlinks in sgskip example

fd07468

Address review feedback

0488e1f

jayaprajapatii force-pushed the fix-svg-hyperlink-doc branch from 31265b8 to 0488e1f Compare May 14, 2026 07:21

jayaprajapatii marked this pull request as ready for review May 14, 2026 07:29

timhoffm merged commit 7499f38 into matplotlib:main May 16, 2026
21 checks passed

QuLogic added this to the v3.11.0 milestone May 16, 2026

meeseeksmachine mentioned this pull request May 16, 2026

Backport PR #31497 on branch v3.11.x (DOC: Clarify SVG hyperlink behavior in gallery hyperlinks example) #31683

Merged

timhoffm pushed a commit that referenced this pull request May 16, 2026

Backport PR #31497: DOC: Clarify SVG hyperlink behavior in gallery hy…

e168e58

…perlinks example

timhoffm added a commit that referenced this pull request May 16, 2026

Merge pull request #31683 from meeseeksmachine/auto-backport-of-pr-31…

9478117

…497-on-v3.11.x Backport PR #31497 on branch v3.11.x (DOC: Clarify SVG hyperlink behavior in gallery hyperlinks example)

Uh oh!

Conversation

jayaprajapatii commented Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Problem

Solution

Impact

Uh oh!

timhoffm left a comment

Choose a reason for hiding this comment

Uh oh!

jayaprajapatii commented Apr 13, 2026

Uh oh!

timhoffm left a comment

Choose a reason for hiding this comment

Uh oh!

timhoffm Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

timhoffm left a comment

Choose a reason for hiding this comment

Uh oh!

timhoffm Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

jayaprajapatii commented Apr 15, 2026

Uh oh!

jayaprajapatii commented Apr 19, 2026

Uh oh!

timhoffm commented Apr 21, 2026

Uh oh!

jayaprajapatii commented Apr 26, 2026

Uh oh!

timhoffm commented Apr 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jayaprajapatii commented Apr 27, 2026

Uh oh!

timhoffm commented Apr 27, 2026

Uh oh!

jayaprajapatii commented Apr 27, 2026

Uh oh!

timhoffm left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

timhoffm left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

timhoffm commented May 16, 2026

Uh oh!

QuLogic commented May 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jayaprajapatii commented Apr 13, 2026 •

edited

Loading

timhoffm commented Apr 26, 2026 •

edited

Loading