How to refer to a static resource?

[luizirber]

Hello,

I'm currently moving the last bits of our docs from RST to md using MyST but I couldn't figure out how to link to files in the _static/ dir. What is the right syntax for that?

Thanks!

[choldgraf]

Hmm, can you give an idea of how this would look in rst?

[chrisjsewell]

(@choldgraf you beat me to it)

Heya @luizirber, could you expand on "link to". Do you mean show images from this folder? If so then IRC you could use ![Alt](../path/to/_src), where the path is relative to the markdown file. Maybe you could provide the current rST you are using to do this.

[luizirber]

More info:

I'm trying to fix this page (rendered). This works both in Sphinx (for readthedocs) and in GitHub, but when I try to use MyST it complains:

doc/other-languages.md:35: WARNING: None:myst reference target not found: _static/ecoli-cmp.Rmd

recommonmark also throws the same warning:

doc/other-languages.md:35: WARNING: None:any reference target not found: _static/ecoli-cmp.html

---

I tried using the download directive, like this:

{download}`See the output of plotting and clustering this matrix <_static/ecoli-cmp.html>`

and it works, but it forces a download (while the current solution with recommonmark opens the HTML file in the browser).

---

So I guess I'm asking what is the proper way of doing it without throwing a warning in Sphinx. Is there something similar to the download directive that allows linking to files in _static? Should I just ignore the warning?

(and thanks again for taking time to answer, because I realise it is not necessarily a MyST-related issue...)

[choldgraf]

Ah so what you've got is an HTML file in your source files (in _static) and you want people to click a link to that file and have it open as a "regular" HTML file, yeah?

It sounds like Sphinx is trying to resolve _static/ecoli-cmp.html as a document not as a raw file, which is why the warning is being thrown.

[chrisjsewell]

and thanks again for taking time to answer, because I realise it is not necessarily a MyST-related issue

Oh no I can definitely see the use case 👍

This works both in Sphinx (for readthedocs)

Not sure what you mean by this? As in there is an existing rST directive that you use that achieves this?

it forces a download (while the current solution with recommonmark opens the HTML file in the browser)

What do you mean by "the current solution", is this something different to using the download directive?

It sounds like Sphinx is trying to resolve _static/ecoli-cmp.html as a document not as a raw file

Yes, currently this [](_static/ecoli-cmp.Rmd) will first try to look for a matching reference name, then a matching parsed document; e.g. only those with extensions matching .rst or .md. The sphinx solution, that I know of to achieve this, is to use a literal include in an "orphaned" file, which is what I have used before in e.g. https://github.com/chrisjsewell/ipypublish/blob/develop/docs/source/metadata_cell_schema.rst, then you link to this file [](outline_schema.rst). But yes a simpler solution would be ideal

[egolearner]

Is there any update on the issue?

We get the same problem trying to link to local static html files.

For whom may be concerned, there is a workaround using eval-rst.

```{eval-rst}
   `Python API <..>`_
```

[jpmckinney]

Same as #215?

[nightlark]

I'm having this issue, with html generated by doxygen. In my conf.py for RTD I add the output from doxygen using html_extra_path.

Previously with recommonmark, ## [C++ API (doxygen)](../../doxygen/index.html) was getting turned into a relative link to the right place. Myst-parser is turning it <span class="xref myst">C++ API (doxygen)</span> which is very much not a link in any way, shape, or form, and also differs from GitHub which also turns it into a relative link to a (albeit non-existent) html file.

Changing the behavior to make it at least an <a href=... when it can't find a valid xref to a markdown file seems like it would be a sane default that puts the behavior in line with how other parsers handle the situation.

[nightlark]

I'm sure we have other similar relative html links scattered throughout that are now just broken. Having to track them all down and replace them with the {eval-rst} hack is making me wonder if I should skip updating to myst-parser and switch back to recommonmark until there is a better way to handle these links.

Though doc builds breaking was part of the motivation for switching in the first place, so its a bit of a conundrum.

[asymmetric]

Another workaround is to just insert <a href="./_static/foo/bar.html"> elements, instead of anything that myst-parser can catch and turn into a "download" link.