Simple Middleman Blog Search with Awesomplete

This is a post about developing my blog on my blog - take a second to appreciate how meta that is.

I recently transitioned my personal site from Wordpress to a static site on Github pages built using Middleman. Overall it was an awesome change and I feel much better having my personal site and assets etc in plain text and source control. The transition was pretty smooth however there were a few things that I had with Wordpress that took a bit of finesse to acheive with Middleman. Blog search was one of those things and I eventually came up with a pretty elegant solution that I would like to share here.

The reason search is interesting is because Middleman generates static sites which means any search solution needs to be entirely client side. If you google for Middleman search you’ll find some other projects and gems but I think my solution is simpler.

I built my blog search using this nice little autocomplete library call Awesomplete. To start I add the following markup to the sidebar partial which is rendered on all the blog sections of my website:

<input id="search" class="form-control" list="articleList" placeholder="Search...">
<datalist id="articleList">
  <% blog.articles.each do |article| %>
    <option><%= article.title %></option>
  <% end %>

This creates the base list of all my blog articles. Now we need to bring it to life with Awesomplete:

  var input = $("#search")[0];
  var awesomplete = new Awesomplete(input, {
    minChars: 1,
    maxItems: 5,
    autoFirst: true

  var searchIdx = {
    <% blog.articles.each do |article| %>
      <%= article.title.to_json %>: "<%= article.url %>",
    <% end %>

  window.addEventListener("awesomplete-selectcomplete", function(e) {
    var articleTitle = $(;
    var articleUrl = searchIdx[articleTitle];

This code does a couple of things - first it initializes the Awesomplete widget. Next it defines a searchIdx variable which just maps article title to url and stores it in javascript land so we can access it later. The last bit of code listens to the awesomplete-selectcomplete event then looks up the url for the selected article and then loads the page with Turbolinks (if you’re not familiar this is just a slicker way of doing window.location = ).

I was really happy how this turned out, super fast, simple and the code is nicely contained in my sidebar partial. Give it a try in the search box to the right!

read more

Apipie example recording with Minitest

I’ve been using the excellent apipie gem on a new project I’m working on and I wanted to share my solution for example recording with Minitest. The gem documentation has an example of how to specify which functional tests should be shown as an Api example if you happen to be using Rspec but nothing for Minitest - what to do?

If you read the source of the example recorder it’s actually pretty smart - it loads the apipie_examples.json file of the previously recorded examples and only adds new ones or updates existing examples. With this knowledge I came up with an approach - I added a special string #apidoc to the test name of the tests I want included in my Api docs. Then I made this Rake task to run only my Api controller tests and filter which tests using the string:

task :api_examples do
  Dir["#{Rails.root}/test/controllers/api/*controller_test.rb"].each do |controller|
    pipe = IO.popen("APIPIE_RECORD=examples bundle exec ruby -Itest #{controller} -n /#apidoc/")
    while (line = pipe.gets); print line; end

Also make sure you have config.show_all_examples = 1 in your apipie initializer file.

That’s how I did and it’s been working nicely for me, let me know in the comments if you have a better solution!

read more

Some fun with D3.js

I’ve been intrigued by D3.js and the impressive visualizations I’ve seen people make for quite some time and I finally got to check it out for myself. I wanted to write this blog post sharing my experiences and revelations from the perspective of someone who at one point spent a fair amount of time with Matlab/Octave and my personal fave matplotlib.

The first major point I want to make is that D3.js is not a plotting library - it should not be compared directly to Matlab/Octave or matplotlib because they serve different purposes. D3.js is a visualization library, sure this visualization may be a graph but you shouldn’t be playing with D3.js until you already understand your data and simply want to show it off. While exploring and figuring out your data matplotlib is going to be way faster and more effective (note there are some wrappers building standard plotting functions ontop of D3.js like NVD3 if javascript is really your thing).

Once you’ve figured out your data and it’s time to show-off D3.js really shines and here is the main reason why in my opinion. It’s due to a fundamental shift in a way of thinking that makes D3.js so powerful: rather than calling plot with an array of x and y values I am binding an array of javascript objects to my plot and then telling it which attributes to use for different things. Essentially you are pulling more data into the plot and you can write code at each level - let me show you the snippet that made me realize how powerful this shift in thinking is:

var chart =".chart");

var tip = d3.tip()
.attr('class', 'd3-tip')
.offset([-10, 0])
.html(function(d) { return "<span>" + d.text + "</span>"; });;

var bar = chart.selectAll("g")
.attr("transform", function(d, i) { return "translate(" + i * barWidth + ",0)"; });

.attr("y", function(d) { return y(d.value); })
.attr("height", function(d) { return height - y(d.value); })
.attr("width", barWidth - 1)
.on('mouseout', tip.hide);

The important parts to note are this: I grab the value for my y axis of the rect from d.value where d is one of the objects in my data array that I am plotting. So far this is pretty standard but look at the tip function that gets called on mouseover - it shows a span which contains d.text! I’ve attached another piece of data here called text that can be used to display more information! This was the wow moment for me because this kind of thing isn’t possible in matplotlib and showing a simple tooltip is really on the beginning of what you can do with all this added context.

Also something about plots with a :hover effect is kind of awesome!

If you haven’t played with D3 yet and have some cool data I definetly recommend it, I used it to make some pretty sweet visualizations/tools for our Parity Ultimate Frisbee League here in Ottawa, check’em out:

read more