The secret to referencing Middleman's asset_hash-ed assets


Having a hell of a time getting your blog posts to reference Middleman’s asset_hash-ed assets and making use of article subdirectories? I was too: to the tune of two hours of rabbit-holeing on the problem.

But I’ve got the key to it here to share with you, fellow wayward code traveler.

It’s all about source paths

Whether you need to reference the asset in a blog post or in a helper somewhere, you must make use of Middleman’s source path to the asset.

For example, if my blog is at /blog, and my article is named something like: 2014-09-17-zurb-s-foundation-why-it-s-time-to-switch.html.markdown (generated by middleman article), the source path to my article is: /blog/2014-09-17-zurb-s-foundation-why-it-s-time-to-switch/index.html (if using activate :directory_indexes) or /blog/2014-09-17-zurb-s-foundation-why-it-s-time-to-switch.html if not.

In either case, when using article subdirectories for assets, there is a folder: /blog/2014-09-17-zurb-s-foundation-why-it-s-time-to-switch/ which contains my assets.

Now remember, when I say folder, for now, we are only talking about source paths: the paths Middleman makes use of prior to building final output paths, under your /source directory. The paths you develop against before running middleman build. The main difference between source paths and output paths is that the date gets converted from dashes to slashes in output paths: from /blog/2014-09-17-zurb-s-foundation-why-it-s-time-to-switch to /blog/2014/09/17/zurb-s-foundation-why-it-s-time-to-switch. Of course, other wild stuff can happen with output paths depending on plugins you’re using, etc.

We good so far? Good. Now we’ve got our source path folder for the article’s assets: /blog/2014-09-17-zurb-s-foundation-why-it-s-time-to-switch/. What we want to do from here is, in our 2014-09-17-zurb-s-foundation-why-it-s-time-to-switch.html.markdown file, refer to the asset in question like so:

![My Image](/blog/2014-09-17-zurb-s-foundation-why-it-s-time-to-switch/uber_nav.png "My Image")

Note that we are using the correct source path to the article subdirectory, /blog/2014-09-17-zurb-s-foundation-why-it-s-time-to-switch/, and then appending the actual image to it (uber_nav.png). When we do the above, Middleman generates an image_tag for this source path. The image_tag helper in Middleman is implemented using Middleman’s own url_for, which is responsible for converting these source paths into output paths.

In this case you will find the output path, assigned as the value for the srcattribute to the <img> tag, to be something like /blog/2014/09/17/zurb-s-foundation-why-it-s-time-to-switch/uber_nav-12323.png if it worked (or simply uber_nav-12323.png if you’re using relative paths). Glorious! How relieved I was when that worked!

I need attributes and stuff

Things get slightly more complicated if you want to add additional attributes to your image that the markdown image syntax can’t handle.

First, you need to append .erb to the filename, like so: 2014-09-17-zurb-s-foundation-why-it-s-time-to-switch.html.markdown.erb. Once you’ve done that you can go ahead and convert the above image markdown syntax into something like this:

<%= image_tag '/blog/2014/09/17/zurb-s-foundation-why-it-s-time-to-switch/uber_nav-428144d3.png', class: 'something cool', width: '50%' %>

Remember, this will take the source path above and call url_for with it, getting you the asset_hash-ed image. Nice!

A note on referencing asset_hash-ed assets properly within custom helpers

If you’ve got some custom helper code like I did that generates asset paths for you, remember the above concepts. You need to first get the source path to the asset, and then you can call url_for(source_path_to_asset), just like Middleman does internally, to get the asset with its hashed filename.

Disable activate :cache_buster!

Do that, because I’ve heard these conflict with one another. They are two different ways of handling caching, with cache_buster appending a query param instead of rewriting the filename like asset_hash does.

Want more?

Get the latest ruby news, tips, tricks, and GOTCHAS delivered straight to your inbox.

comments powered by Disqus