Hash our CSS/JS assets with digest requests instead of in filenames

[choldgraf]

Summary

In #373 we learned that it is difficult to sub-theme this theme because of the hashes in the CSS / JS assets. @pradyunsg shared a solution that has worked for Furo, which uses Digest headers to specify a specific version of the JS/CSS assets. Here's the commit that added it in Furo:

pradyunsg/furo@11dc2ee

We could follow a similar pattern in this theme, which would make it easier for sub-themes to depend on it since they won't need to know the hash ahead of time, they can just specify a CSS file.

Implementation

We currently use a pre-commit hook to generate hashed CSS, JS, and a theme.conf file that addresses these hashed assets. Here's the asset compilation configuration for our pre-commit hook. Instead of specifying the hashes in filenames, we could create / append the hashes at Sphinx build time, following a similar pattern to what Furo does in the commit above.

[pradyunsg]

Digest headers t

Furo isn't using the digest headers -- it's putting the hash as furo.css?digest=[hash] instead of furo.[hash].css.

[choldgraf]

@pradyunsg ah that is just me not really understanding what ?digest= really means...I just googled "HTML Digest" and that's what came up. Do you have a link to a resource that explains what this is?

[pradyunsg]

It's basically using the hash of the CSS file's contents for cache busting. A good link on cache busting would be https://css-tricks.com/strategies-for-cache-busting-css/.

A good link on what "digest" means in this context would be https://developer.mozilla.org/en-US/docs/Glossary/Digest (although, we don't care about the integrity/security etc here -- just that it's a hash that changes when the contents change).

SBT is already doing cache busting, by changing the filename and including a hash in it (computed during the pre-commit step). Furo is doing it in a slightly different way, by having a query parameter with the hash instead (computed during the Sphinx build).

[choldgraf]

This is very helpful for me to understand, thanks for sharing those links 🙂