Support in Markdown documents

[harrytodorov]

Hello kind developers,

Recently I had the task of integrating your extension in the docs of one of our products. I've liked the simplicity and visual reconfigurability of your extension.

However, our documentation is currently mostly written using CommonMark (through the recommonmark extension). That made the integration of your extension quite tedious and polluted our docs. We had to use special code blocks (for evaluating ReStructuredText) for each paragraph, where there was a term needing a tooltip:

```eval_rst
... :hoverxref:`some term <TERM_SOME_TERM>`
```

One of the main drawbacks of this is that you need to manually rewrite existing Markdown code to ReStructuredText in the paragraphs tooltips needed to be added.

In turn, this forced us to heavily reduce the number of places where would like to add tooltips. To my knowledge, there is also no option of inlining ReStructuredText in Markdown (that would have been a good compromise).

So the bottom line: from the perspective of our project, adding Markdown support would heavily increase the ease (and joy) of using your extension.

[stsewd]

Hi, we recommend using myst instead of recommonmark if you want to author your docs using markdown https://myst-parser.readthedocs.io/en/latest/using/intro.html. MySt maps more nicely to the rst syntax. There isn't much we can do from the extension side to make it more easy with recommonmark.

[humitos]

Hi @harrytodorov! Take into account that recommonmark is dropping official support, please read: readthedocs/recommonmark#221

I don't think we will implement support for it in this extension for that reason. I'd encourage you to test MyST-parser as @stsewd suggested and let us know if this extension works properly with MyST. I'd be happy to make the adjustments required to make it work there if any.

[harrytodorov]

Hi @humitos! Thanks for the update on the issue!

We were not aware of this change. We have made the choice back then to use the recommonmark extension following the official suggestion from Sphinx (see here).

We will now follow the development and if we transition to MySt, then we can try to integrate hoverxref once again.

[humitos]

Great! Feel free to open an issue here if you find any problem with this extension! Thanks!