document or improve handling of `_static` when coming from jb1

[parmentelat]

foreword

I am coming from jb1/sphinx; for handling some types of media, I have had to - at some point in time at least, I've had no other choice than to - store some kinds of media under the _static folder, so as to ensure it would be part of the generated book

specifically I've gotten used to doing like that for at least

• html documents (think e.g. folium-generated maps, or self-contained cheatsheets,...) that I want to include via an iframe
• videos (I have seen the mystmd tool is much better equipped for handling them now, but in the perspective of a smooth transition it may make sense to mention them here)
• and more generally everything that's a bit unconventional and that, again, we want to make sure to bundle with the output

my problem

let me focus on the html category for now; I had this guinea pig jb1 project here https://jupyterlab-examples.readthedocs.io/en/main/1-05-iframes-nb.html#use-ipython-s-iframe-instead

and I don't know how to translate this into jb2 if I write e.g.

    ```{iframe} _static/cheatsheet.html

 ````

then I'm getting an iframe .. with inside a myst theme featuring a "Document not found"

ps: this is an attempt at replying to @choldgraf's request for clarification in https://github.com/executablebooks/mystmd/issues/1228#issuecomment-2135524413 sorry this is probably still rather confused but hopefully a little more helpful please feel free to change this issue title, and to make it more specific if needed

[rowanc1]

Thanks @parmentelat -- your issue makes a lot of sense, and thanks for the descriptions of your current use case, very helpful. Happy to see that we have made some improvements on the videos. :)

This is a related issue:

• 1196

Currently I don't think this is very possible in mystmd, we hash the output files to ensure all caches are busted, but that means the links are not stable, and the iframe doesn't look to the local filesystem at this point.

I think there are a few ways to go - (1) give a static directory similar to sphinx; (2) expand the argument of the iframe to allow local HTML files. I think that probably (2) is going to have problems, especially if there are any other assets that are loaded by the iframe, so (1) is probably the right way to go here.