Custom 404 page with Middleman on Amazon S3

While we continue to improve our website, one of the things that was getting really annoying was this “beautiful” error page that AWS shows when navigating to nonexistent pages:

AWS S3 default 400 error page

We wished there was some Middleman extension that allowed us to configure the bucket’s Error Document, but there isn’t. We then found that middleman-s3_sync, the gem we used for deploying, depends on fog-aws - and that one was able to configure the custom 404 page!

We jumped into the middleman-s3_sync gitter channel, just to check if there was any strong reason why they haven’t integrated integrated that functionality into the extension - and there wasn’t. So we coded it, and now middleman-s3_sync supports specifying which page to show for any 400 error. It also allows you to customise which path to use as directory index, the good old index.html default.

If you want to set a custom 404 page in your Middleman site hosted on Amazon S3, update your Gemfile to use the 3.3.4 version of the gem:

gem 'middleman-s3_sync', '~> 3.3.4'

There’s still no 4.x version of the gem with this changes, but they were merged into master, too - so you can include gem 'middleman-s3_sync', github: 'fredjean/middleman-s3_sync', branch: 'master' until @freadjean cuts a new release.

Then, add something like this in your config.rb:

activate :s3_sync do |s3_sync|
  s3_sync.bucket = @s3[:bucket]
  s3_sync.region = @s3[:region]
  # ...
  s3_sync.index_suffix = 'index.html' # the default, but maybe you want to change it
  s3_sync.error_document = '404.html'
end

And be sure there’s actually a page at $YOUR_SITE/404.html - ie, use page '404.html', directory_index: false if needed.

And that’s it!

You can now brag about your lovely 404 page!

If you were looking for ideas about how to make a nice looking 404 page - you can tell I’m not the best one to ask:

My custom-404-page best try

Thanks $DEITY we have a great designer in our staff - and just people with common sense, for that matter - so we’ll have a better 404 page than that.

That’s what’s so lovely about open source - the extension almost worked for us, and we could fill the gap so it now perfectly fits our needs. You can do it, too - keep on forking in a free world!