Building with Middleman

This post outlines three discoveries from building our new website with Middleman, a framework for creating static websites, using Ruby.

Data files

Data files in Middleman separate chunks of content from the HTML-based layouts. Data files are made even better by the ability to dynamically create pages using these data files.

As an example, information about our apps are stored in data files, then pages are generated for each of the apps with this short snippet in config.rb:

data.apps.each do |app|
  proxy "/#{app.url}/index.html", "/apps/template.html", :locals => { :app => app}, :ignore => true

Search is implemented client-side using Fuse.js, a tiny fuzzy-search JavaScript library. Fuse.js searches over a JSON search corpus (we've done some minimal optional processing to remove stop words), then search results are rendered with Handlebars.

The outcome is nearly instant search, given our small search corpus.

Feedback events

On support articles, we ask "was this article helpful?", with "yes" and "no" buttons. We found Google Analytics events was a simple solution to collect feedback on content, without having to write any server-side code.

Once you've set up Google Analytics, in JavaScript all you need is a simple function that wraps the basic events code:

var sendFeedbackEvent = function (action) {
  ga('send', {
    hitType: 'event',
    eventCategory: 'Feedback',
    eventAction: action,
    eventLabel: 'Support article'

Then, when users click the helpful/unhelpful button, you can dispatch the relevant event: