Jekyll Version of Pattern Primer

A pattern documentation tool for designing websites, based on Jeremy Keith’s Pattern Primer.

This project was originally completed and worked on from 2013-07 to present.

This writing was last updated 2014-12-01.

On a lazy Saturday afternoon in the early stages of designing Jean’s website, I was reading about pattern libraries and related design communication tools. A simple and straightforward implementation that appealed to me was Jeremy Keith’s Pattern Primer (view source). The idea is that you take a folder of HTML snippets and then test them against your own CSS file. The result is a self-generating and self-documenting set of HTML patterns, alongside the CSS for a project. The primer includes some useful HTML samples to start off with, but any HTML snippets could be used.

I thought it would be straightforward enough to port to Jekyll, which I use to build websites. This suited my workflow since I could use it with my Jekyll projects with only Jekyll dependencies (and no PHP dependencies). This way I could run my pattern primer on a local machine or deploy it just about anywhere as static HTML, the same as any other Jekyll site.

Why document patterns?

While working on a project, it can be helpful to both designers, developers and others involved to abstract patterns – both structural (HTML) and presentational (CSS). That is:

… beginning with the atomic units of content and styling them first before even thinking about layout. This ensures that those styles are extremely robust—because they don’t depend on any particular context, they can be safely dropped into any part of a page.

Pattern Primer (as well as many other similar tools) can be used as design clarification and communication tools at any stage in a design process. This approach is quite useful near the beginning of a project, to make sure that design patterns can stand on their own as atomic units.

Heading styles in Pattern Primer Jekyll

Find out how your headings look and what markup is needed for them with a primer.


I forked Jeremy’s source from GitHub, and faithfully re-worked the minimal set of features in Jekyll. I did not change the base styles, so what you see on the finished page is exactly what you see in the original project. It took me less time to implement the features of Pattern Primer than it did to write and edit the brief documentation for it and set up Amazon S3 to host it.

What I learned from this project