Determining a page is outdated on github pages

Github pages sets very aggressive cache headers (Cache-Control: max-age=86400 1 day, Expires 1 month ahead) on all served content.

If you update your pages and push to github, people revisiting the pages who have already got cached copies will not get the new pages without actually cleaning their browser cache.

How can a script running in a page determine that it is stale and force an update?

The steps might be:

1. determine you are running on github pages: easy, parse window.location for github.com/
2. determine current version of page: hard, git doesn’t let you embed the sha1 in a commited page; no RCS $id$. So how do you know what version you are?
3. get the current version in github; hard, github got rid of non-authenticated v2 API. And there’s a time disconnect between pushing to github and github getting around to publishing too. So how do you know what version you could get?
4. having determined you’re stale, how do invalidate a page and force reload? hard, window.location.reload(true) doesn’t work in Safari/Chrome, for example…

So its solve-these-steps; of course there may be another way?

Answer

To have a better control of the caching of your website you can use the HTML5 cache manifest. See:

• A Beginner’s Guide to Using the Application Cache on HTML5 Rocks
• Using the application cache on Mozilla Developer Network
• Cache manifest in HTML5 on Wikipedia
• Offline Web Applications W3C Working Group Note
• Offline Web applications at WHATWG

You can use the window.applicationCache.swapCache() to update the cached version of your website without the need for manually reloading the page.

This is a code example from HTML5 Rocks explaining how to update users to the newest version of your site:

// Check if a new cache is available on page load.
window.addEventListener('load', function(e) {

  window.applicationCache.addEventListener('updateready', function(e) {
    if (window.applicationCache.status == window.applicationCache.UPDATEREADY) {
      // Browser downloaded a new app cache.
      // Swap it in and reload the page to get the new hotness.
      window.applicationCache.swapCache();
      if (confirm('A new version of this site is available. Load it?')) {
        window.location.reload();
      }
    } else {
      // Manifest didn't changed. Nothing new to server.
    }
  }, false);

}, false);

To avoid some confusion I’ll add that GitHub sets the correct HTTP headers for cache.manifest files:

Content-Type: text/cache-manifest
Cache-Control: max-age=0
Expires: [CURRENT TIME]

so your browser knows that it’s a cache manifest and that it should always be checked for new versions.