Keep links stable for static assets while retaining cache busting

[choldgraf]

Currently when static assets are linked to a MyST site build, their URL gets generated with a hash that is part of the filename. This is done to ensure that the cache is busted if the file is updated.

For example, using {download}`myfile.png` results in a filename like mysite.org/build/myfile-c7e3595ff6c09f5cc22cc52b8177cd4c.png)

The problem with this is that if you want to directly link to a static asset elsewhere, the link will be invalidated as soon as the MyST site is rebuilt, because the hash is included in the filename itself.

It would be useful if the URL for static assets was persistent as long as the user didn't change the filename, so that external links to them remained valid.

Potential solution: cache busting

One option is to use a query parameter to bust caches, rather than putting the hash in the filename.

Essentially you'd move the hash from this:

mysite.org/build/myfile-c7e3595ff6c09f5cc22cc52b8177cd4c.png

to this:

mysite.org/build/myfile.png?v=c7e3595ff6c09f5cc22cc52b8177cd4c

The hash becomes part of a "query" parameter. You can thus still link directly to the file (mysite.org/build/myfile.png) and links on the MyST site will include the hash via the query parameter so you'll cache-bust as expected.

References

• Here's a StackOverflow post about it.
• Issue where this raised a problem: Link broken for impact pdf download 2i2c-org/2i2c-org.github.io#238