Improving Cacheability

To make your website render as quickly as possible, you should serve any assets, like JavaScript, CSS, or images, with proper headers that instruct web browsers to cache them for a very long time. This means that when users visit your site again (or even just go to another page in your site) they don't have to re-download those assets. However, setting a far-future Expires or Cache-Control header can cause problems when you change your assets but users are still using their cached versions. Middleman has two approaches to solve this problem for you.

Uniquely-named assets

The most effective technique for preventing users from using outdated files is to change the asset's filename every time you change one of your assets. Since that would be a pain to do by hand, Middleman comes with an :asset_hash extension that does it for you. First, activate the extension in your config.rb:

activate :asset_hash

Now, refer to your assets as normal, with their original filename. You can use helpers like image_tag as well. However, when your site is built, each asset will be produced with a bit of extra text at the end of the filename that is tied to the content of the file, and all of your other files (HTML, CSS, JavaScript, etc) will be changed to reference that unique-ified filename instead of the original one. Now you can serve your assets with a "never expire" policy, but be sure that when you change them, they'll show up as a different filename.

However, because this extension works by rewriting your files to reference the renamed assets, it's possible the extension might mess up and miss a reference, or do something you don't want to your code. In that case, you might have to fall back to the older cache buster method.

If you want to exclude any files from being renamed, pass the :ignore option when activating :asset_hash, and give it one or more globs, regexes, or procs that identify the files to ignore. Likewise, you can pass an :exts option to change which file extensions are renamed.

Configuring your server

Configuring your server to use far-future Expires and Cache-Control headers is different depending on which server you use. See Google's page speed docs for links on how to configure your particular server, and run Google Page Speed or YSlow to check that you've configured things correctly.