Support Markdown links on MyST

[jhj0411jhj]

I love the features you provide. But I'm writing Sphinx docs with markdown (myst-parser).

For example, I often write a link to other documents in my docs (markdown):

[Another guide](./xxx/some_file)

I wish when I hover over the markdown link, a preview of that doc is shown. Is it possible to support hoverxref in markdown? Thanks.

[jhj0411jhj]

I've noticed this issue #114. And I find the ref syntex provided by my-st is useful: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#targets-and-cross-referencing

{ref}`my text <header_target>`

I'm wondering whether hoverxref_auto_ref can identify and convert markdown links ({any} role?) written by [name](file) automatically.

[jhj0411jhj]

I find a solution.

First, generate section label:

extensions += ['sphinx.ext.autosectionlabel']
# Make sure the target is unique
autosectionlabel_prefix_document = True
autosectionlabel_maxdepth = None

Then use {ref} provided by myst-parser in markdown:

{ref}`design principle <overview/overview:design principle>`

hoverxref will identify the ref above.

However, the markdown links cannot be identified:

using sphinx.ext.autosectionlabel:
[](<overview/overview:design principle>)

using markdown anchor. for example, set `myst_heading_anchors = 3` 
[](../overview/overview.md#design-principle)

So I have to rewrite all my links using {ref}. Is there any way to avoid rewriting existing markdown links ([text](file#header))?

[kiteloopdesign]

Hi, same question/issue here with Myst markdown in Sphinx. Commenting here for visibility.

[humitos]

Hi all! I don't have too much experience working with MyST and how it generates the nodes. It makes sense that it works when using {ref} in your links since that's a Sphinx role and it's translated into a ref node in docutils.

However, I'm not sure to what node [text](file#header) translates to. We will need to figure it out that first. Once we know it, we can probably add a small chunk of code to this extension to handle those as ref as well.

[benjaoming]

What do you make of these @humitos ?

https://myst-parser.readthedocs.io/en/latest/develop/architecture.html#a-sphinx-parser
https://myst-parser.readthedocs.io/en/latest/develop/background.html#the-relationship-between-myst-restructuredtext-and-sphinx

[chrisjsewell]

Hey gang, so yeh I wanted this also, plus didn't really like the whole having to have it hosted on RTD to get it working.

So I created my own extension 😅, that works by pre-compiling all the tips, rather than fetching them interactively (and also supports other APIs like wikipedia and DOI)

Here it is: https://sphinx-tippy.readthedocs.io, and you can see it in action on https://myst-parser.readthedocs.io

happy to work with you guys on it

[FlyingToto]

Hello Everyone,
I am sorry but I can't figure out from the docs above how to get these tippy tooltips to work with Myst Markdown.
We use: md files -> myst -> sphinx -> github -> readthedocs

We basically have 3 simple use-cases when the mouse hovers our keyword 'foo':

• show 1 line tooltip: just display the string "Hello World!"
• show multi-lines tooltip: just display the text:
  "Hello line1 !
  Hello line2!"
  when the mouse over the keyword.
• show a box with the content of another html page: hello_world.html ? (although I assume we write the file as hello_world.md and it get translated to hello_world.html by myst+sphinx)

...I am very new to this whole markdown things, so I apologize if my question is somehow obvious...
for instance for item 1,
I did add to my md file: "Custom tip" which I stole from your tippy doc source code.
but it only show the link in the bottom left corner of my browser no tooltip is showing.
I think I did configure some of tippy properly because I do see some tooltip showing up when I hover over some of my headers in the menu...

Thank you so much!

[LecrisUT]

Am I doing something wrong, or are external roles not supported? I tried on a .md file as:

{external+rtd:std:doc}`test<intro/getting-started-with-sphinx>`

but that did not seem to work. ref with hoverxref_auto_ref seemed to work, but I am not sure how to translate the equivalent of <inv:rtd:std:doc#intro/getting-started-with-sphinx> to that. I've also tried doc as:

{doc}`test<rtd:index>`

~~but that did not work either. ~~ Actually it works, I did not configure hoverxref_intersphinx appropriately

Basically what would be the minimum setup and supported roles that could be used? Ideally compared to myst documentation here and here

[LecrisUT]

@humitos is this reference useful? Or maybe the class of that caller is needed?