May 25, 2016 by Alan Crissey

How We Built the MailChimp Style Guide

Since its launch in August of last year, MailChimp's public, open source style guide has served as a helpful resource for MailChimp employees and outside organizations alike. Over the past few months, we've received a lot of questions asking how we built it, so we thought we'd shed some light on the topic—along with insight into how we build many of our other websites as well.

The power of Markdown

From the very beginning, the style guide presented us with two big problems to solve:

  1. How can we make it easier for our writers to create content for static websites?
  2. How can we create open-source content in a guide format?

If you look at the repo, you’ll notice that it only contains Markdown files. Markdown is a shorthand version of HTML that's much easier to read, write, and edit than regular HTML code. It's a simple text file with an extension of .markdown or .md. Developing our content in Markdown format allows our writers to create and edit for the website without having to touch any code. This makes things a lot easier for them, and helped us address the first of our 2 problems.

From a structure perspective, we decided to follow the same content structure that we use for our collection of guides. The style guide is unique, however, in that the content is publicly available on GitHub, allowing others to fork their own version or contribute with pull requests. This was a new approach, and it helped us solve the second problem.

Getting content to the web

The style guide, like our other websites, was built using Middleman, a Ruby-based static site generator. Static sites have no database, and most work with Markdown out of the box. Middleman parses files with the Markdown extensions—first as Markdown, then as HTML. The double extension on the files in the repo tell Middleman to render them as HTML. We included the public content as a submodule, which Middleman consumes and uses to generate pages.


You may have noticed that there's some extra content at the beginning of our Markdown files that looks something like this:

title: Welcome to the MailChimp Content Style Guide
layout: article

This is extra data, in .yaml format and referred to as Frontmatter, that can be parsed by static site generators for storing information that’s not necessarily content. For example, layout: here refers to the template that should be used to display the page. GitHub reads this information and displays it as a table.

Language choices

Middleman works well for us because it has a lot of built-in flexibility. We can write front-end code in our preferred languages—HAML, Sass, and CoffeeScript—by simply changing the file extension, and further extend its core functionality with custom Ruby helpers and classes. Performance is very important to us and since there is no database, the pages are served up blazing fast.

In addition to Middleman, we also have our own custom front-end framework called Bananabin that allows us to build new sites with custom layouts quickly and easily. Here are a few other examples of sites we've built using Middleman and Bananabin:

Take Middleman for a test drive

We’ve set up an example Middleman configuration on GitHub, complete with instructions on how to get it up and running in the readme. It includes our style guide repo as a submodule that you can swap with your own fork.

The content in the submodule is displayed thanks to one special bit of code in config.rb: :source, path: "content-style-guide",
                         only: /\.html\.md$/

This watches files found in /content-style-guide as if they were in the /source folder, adds them to the sitemap, and only includes files with an .html extension.

Plenty of options

If Middleman isn't a great fit or Ruby’s not your language of choice, there are plenty of other static site generators available. There's an extensive list available on the StaticGen website that ranks generators in order of their popularity and allows you to filter the options by their core language. Some, like Middleman and Jekyll, can even be hosted on GitHub in a gh-pages branch, eliminating the need for hosting the site elsewhere.

Hopefully this provides some useful insight into our thought process behind building websites at MailChimp. Keep in mind, though, that what works well for our team might not be the best fit for everyone. It's important to take the time to find the right tools for your project—you'll be glad you did.


  • David Martinez

    05.25.2016 - reply

    This is really great information. Coming from a designer’s view who understands HTML and Markdown, the idea of the ‘static site generators’ is new to me, so I found that part illuminating. There’s something magical about creating a MD based website, and having something like Middleman turn it into working HTML.

  • Kaelig

    06.01.2016 - reply

    Thank you for sharing so openly the things you are building.