Cache Busting

[KerimG]

Is there any way to make mkdocs build the site with some hash string built into the names of the CSS and JS files to do some cache busting?

[waylan]

No, not that I'm aware of. MkDocs only copies CSS and JS files without modification. Plugins don't even get access to those files.

[KerimG]

What's the current common way of making sure the website and script assets aren't loaded from the cache?
I guess some hacky headers could do the trick but many host their docs on managed webspaces.

[waylan]

MkDocs is a static site generator. Static pages don't need to be concerned with such things. If you need this sort of thing, then perhaps MkDocs is not the right tool for you.

[KerimG]

That is a bit of a silly non-answer. If your STATIC* website uses CSS or JS, being able to bust the cache is a useful thing.

A custom theme might have a small error that needs fixing, the JS might contain an API key (e.g. analytics) that might need updating. Waiting for the cache time to run out might not be feasible, neither is sending HTTP headers to direct the browser to not cache anything. Managed web spaces, which are a prime hosting solutions for static websites, might not even allow modified headers.

[lovelydinosaur]

MkDocs doesn't support this, no.

Yes, in some cases you might be behind a cache, but they won't be setting far-future expiries.

GitHub pages is a good example that's got a fairly heavy caching policy, even then worst case is your page will be up to date in <60 seconds from deployment.

[oprypin]

Why was this closed? Clearly, many people think that this is a needed feature. And it is not solved. If the maintainers don't understand the use case, they should continue asking, not just outright tell people what they should or shouldn't be doing.

---

I have observed this myself many times: in typical configurations of webservers, the browser will end up requesting the HTML anew every time, but CSS linked from the page will be persisted.

And certainly, if I rework, say, the namings of all classes in both the CSS and HTML of my site, I need to ensure that the CSS will be reloaded, not just the HTML. Otherwise, with deep enough changes, my site will end up basically unstyled.
And adding some hash to the CSS's source location is the industry-standard way of achieving this. It makes no difference if the site is static or not, unless it's "static" in the sense of "will never change".

You can try going to https://oprypin.github.io/crsfml/ which is a MkDocs site hosted on GitHub Pages.
What you'll observe is that your Web browser will re-download the page itself every time, but it will persist the CSS linked from it. Even F5 won't reload it.

Cold load (requests filtered to just CSS)	After pressing F5 (all requests)

In this example we have 5 CSS files.

• Two of them with hashes, because mkdocs-material theme itself thoughtfully includes those.
  • So it is indeed fine for the browser to forever cache those files, as files with those particular names will never change.
• The font presumably will never change, so that's fine.
• And the latter two are normal CSS added through MkDocs, and they have no hashes.
  • If I change anything in those files, users of my site can open the home page, and even press Reload, and they will still be seeing the old CSS with new content. That is a problem.

And MkDocs is exactly the tool that should be helpful in this regard. Rather than asking creators to make sure to rename their file to "style2.css" "style3.css" every time, it could very easily load the URL "style.css?d41d8cd9" instead of "style.css", and everything would just be better.

[KerimG]

@oprypin thanks for the effort. I would like to implement this feature but I am not familiar enough with the codebase. We've been using mkdocs as a documentation site for our clients but are considering moving to Gatsby or Next.

[oprypin]

Oh, implementing it is not the problem. Here you go: https://github.com/oprypin/mkdocs/compare/bust
The problem is that this issue is denied.

[waylan]

I went back and reread this. It is clear to me that initially this appeared to be related to server settings/configuration, which is not something that is within MkDocs ability to address (and what he issue was closed). But now it seems that the discussion has turned to browser cache. Although, wouldn't HTTP headers be the way to address this, which again, is a server config thing and out-of-scope for MkDocs? So what do you suggest MkDocs does to address the issue?

[oprypin]

The original issue description suggests this action directly:

make mkdocs build the site with some hash string built into the names of the CSS and JS files

I had also expanded on that in my posts.

---

There is no way to fully control caching through HTTP headers. If a server sets a header saying "browser, please don't even bother checking this file within the next day", then there's no way to undo that by sending a different header next time, because there won't be a next time.

And, well, you can be sure that there are some servers that set that and don't let you change it. GitHub Pages in particular sets it to 10 minutes, but that's just a good bit of luck.

Then you can say "just configure your server to never cache". But that's not a solution, because... caching is nice.

The industry standard practice is to attach a hash to the requested filename, to ensure the browser has not encountered this name before and will request the file anew. At the same time, caching can be configured at "full strength".

You can even look at the <script> tags of this pages's HTML (GitHub).

[KerimG]

My initial post didn't have anything to do with server settings. One can mitigate the issue somewhat with http headers but as @oprypin Pointed out correctly, that's not granular. And that's on the assumption that you can modify the http headers.

I didn't think cache busting is such a controversial issue lol. It's a common thing with virtually every other framework.

[waylan]

Wait, so you mean we need to have a rolling filename which changes with each build. That seems ridiculous. Do other static site generators actually do this?

[KerimG]

Yes. (see second strategy, which is the one I see most often). Files are cached by name, so that's what most frameworks work with. Not sure how this is "ridiculous". I've seen more ridiculous things. Like maintainers of popular static site generators being unaware of that concept and prematurely closing issues related to it 😂

Flask Cache-Busting
Webpack Cache-Busting
Laravel Cache-Busting

Jokes aside, I do think it would be a really cool feature to add.

[waylan]

Those are web frameworks for dynamic content, not static site generates and therefore, didn't answer the question I asked. What does Sphinx or Jekyll do (to name a few)? That said, I couldn't help but notice that for Flask, you linked to an extension. Any reason this couldn't be implemented as a MkDocs plugin?