How to force custom js/css files in Sphinx to always load changes without caching?

Question

In Sphinx's conf.py I have:

html_css_files = ['css/custom.css']
html_js_files = ['js/custom.js']

However if I make any change in custom.js or custom.css then this change does not reflect to in the user's browser unless http://www.example.com/_static/js/custom.js is forcefully reloaded on the client (similarly for CSS).

How can I force the custom CSS + JS to never cache on the user's browser?

Answer 1

Although the config file looks like it only accepts normal string values, it is really just a Python script, so we can import and use functions such as a random number generator.

At the top of conf.py add this line:

from secrets import token_urlsafe

Change your custom CSS + JS to:

html_css_files = [f'css/custom.css?v={token_urlsafe(8)[:8]}']
html_js_files = [f'js/custom.js?v={token_urlsafe(8)[:8]}']

This will make your custom CSS + JS files load like the vanilla CSS + JS files, with a random 8-character slug at the end - thus disabling caching:

<!-- Sphinx vanilla CSS: -->
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />
<link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=19f00094" />
<link rel="stylesheet" type="text/css" href="../_static/copybutton.css?v=76b2166b" />

<!-- Our custom CSS now has a random slug, like vanilla: -->
<link rel="stylesheet" type="text/css" href="../_static/css/custom.css?v=Rdy7RNCQ" />

<!-- Sphinx vanilla JS: -->
<script src="../_static/jquery.js?v=5d32c60e"></script>
<script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js?v=e91dff3d"></script>
<script src="../_static/doctools.js?v=888ff710"></script>
<script src="../_static/sphinx_highlight.js?v=4825356b"></script>
<script src="../_static/clipboard.min.js?v=a7894cd8"></script>
<script src="../_static/copybutton.js?v=f281be69"></script>

<!-- Our custom JS now has a random slug, like vanilla: -->
<script src="../_static/js/custom.js?v=8QronLhw"></script>

Note that if you're running Sphinx in Docker then the ?v=xxxxxxxx slug will not change unless you run your docker build with the --no-cache option.