Skip to content

Building a front-end style guide with Jekyll

A few weeks ago Justin Slack of New Media Labs gave a talk about Front-end Style Guides (FESGs) for the Cape Town Front-end developers meetup. Below are my notes from his talk.

Justin talked about how FESGs are good for modular development, testing code early, and how they set a good precedent. They use real code and run in the browser, making them unlike regular style guides: they’re a living document. The Lonely Planet style guide is particularly impressive because it’s truly living: it uses an API to call view partials.

The options

There are a lot of generation options across a variety of languages: Rails, Ruby, PHP, JavaScript. Jekyll, a static site generator, is one option. A Style Guide needs to start incorporating content, so the fact that Jekyll uses Markdown is great because many content people use it.

Justin gave a short demo of setting up Jekyll and an explanation of how it works. It was great to see it in action. He noted that the built-in syntax highlighting is another good reason to use Jekyll. And, since it generates static web pages, it also has a very small footprint.

The demo

My favourite bit of his presentation was the demonstration of a real world example. Justin talked us through the set up, the thinking behind it, and the continued work on it. It was also great to hear about the bad sides of using Jekyll. Nothing is without its problems, and it was good to hear an honest discussion of the ups and downs. Some of the problems include the fact that it can be slow to use once you have a lot of files.

The next meetup

If we managed to get our skates on, we should be having another meetup next week: keep an eye on the meetup group for details!