To make your website render as quickly as possible, you should serve any
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
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.
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
extension that does it for you. First, activate the extension in your
Now, refer to your assets as normal, with their original filename. You can use
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,
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
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
: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
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
YSlow to check that
you've configured things correctly.