Contribution to Myst-Parser: Links from elements in SVG diagrams to other images or document content

[volkerjaenisch]

Dear Developers!

I have a prototype implementation for links from SVG elements to other images or document content (for HTML output).

This feature comes in really handy if one has diagrams of different detail and like to link from the above-level diagram to sub diagrams. Or linking from a diagram to the definition, documentation, of a diagram portion, or element.

The implemented strategy in overview.

1. We need to have speudo URIs like myst://#the-anchor on elements in the SVG image
2. A new directive e.g. figure-links has to be introduced.
3. Upon sphinx rendering time (of the SVG image) the SVG-File is parsed and the speudo URIs are replaced with relative links into the document.
4. These relative links have to be derived.
5. The (modified) SVG image is then rendered as (as opposed to ) into the HTML output to open its internal structure to the browser.

   [Sorry for the crappy presentation. The markdown here is strange, can someone please tell me what I am doing wrong]

   State of development

   1. Can be done with most SVG authoring software. E.g. the free draw.io is well suited to the task.
   2. Directive is implemented
   3. Is a simple parse an replace task. Not yet implemented but easy to implement.
   4. Calculation of the relative links may be a bit fiddling but it surely can be done.
   5. This needs patching the sphinx HTML4/5-Writer. Code is working.

   The following is already working [omitted the closing ```]:

   # test
   
   ```{figure-links} 
   ![mylinkimage](output.svg){width=200px}
   
   This is the figure-links caption
   
   ```{figure-md} 
   ![mylinkimage](output.svg){width=200px}
   
   This is the figure-md caption
   
   

   See attached result:
   build.tar.gz

   Questions

   • Is there a possibility to extend Myst-parser by plugins?
   • If not, should I write a Sphinx extension for my code?
   • Or should I do a pull request on Myst-Parser itself?

   Cheers,

   Volker

[chrisjsewell]

thanks @volkerjaenisch sounds cool!

I would suggest it would be best to write a "standalone" sphinx extension, since:

1. I don't see anything in your outline that specifically requires upstream changes to myst-parser
2. Then people using both MyST and reStructuredText can benefit

But definitely let us know how it goes 😀

[volkerjaenisch]

Thank you for the lightning fast directions.
Will build a sphinx extension.

Cheers,
Volker

[volkerjaenisch]

The Sphinx extension sphinxcontrib-svg-links 0.1.5 is online on github and PyPI.

Testers, Comments and Criticism are warmly welcome.

There is still a minor problem with MystParser. Its current release 2.0.0 does NOT work with sphinxcontrib-svg-links since the new attribute ":svglinks: True" to the image directive is not correctly handled by MystParser. I tracked the error down to
parsers/directive.py:189

    if not isinstance(value, str):
        if value is True or value is None:
            value = None  # flag converter requires no argument

This effectively sets any attribute to None which was set to True in markdown, which cannot be correct.

This erroneous behavior is already fixed in the current MystParser GH sources. With MystParser from the sources it runs flawlessly.

When to expect a new Release of MystParser?

Cheers
Volker