Front-End Style Guides with Handlebars

There are so many great tools out there to help you generate style guides for your web projects, but it’s often difficult to find one that fits all of your needs. I work on a project where the back-end developers need to create new pages and UI components frequently, but don’t want to have to ask me to write new CSS or update markup every time they do so. This is a clear example of where a front-end style guide would come in handy, something that documents all of the different components and classes available to them and provides code snippets they can reference.

I looked into a number of style guide tools and options, but nothing worked out quite the way I was looking for. I tried writing the documentation in the SCSS itself, but this wasn’t ideal for markup or JavaScript examples, nor was it the right place to be writing lengthy documentation. It looked like the best option was going to be to hand write our style guide, and while I’ve done this before, I wanted a solution that was both malleable and easier to update.

Templating languages

The biggest pain I’ve had when hand writing style guides has been the template itself. Navigation, CSS, JS, and any wrapping elements are annoying to copy and paste over and over, and if you make a change to one of those, you have to update it across potentially hundreds of files. There are lots of different ways you could approach this, but I thought a JavaScript-based templating language would work for us.

Handlebars to the rescue

I decided to give Handlebars a try because it:

• seemed to be easy to setup and maintain;

• had clear documentation and plenty of tutorials;

• allows for if/else statements and each loops; and

• is mostly JavaScript, so it could easily be updated by any of our developers.

There are a lot of great tutorials to get you started if you’re unfamiliar with Handlebars, but the basic premise is:

• Create a Handlebars template with your desired markup

• Include any dynamic variables as expressions

• Compile your Handlebars template(s)

• Create an HTML file for your new page and call the Handlebars library

• Create JSON objects to define the dynamic variables and pass them to your Handlebars template

• Append your template to the page

Note: I prefer to pre-compile my Handlebars templates. You can learn more about pre-compiling and Handlebars in general via SitePoint’s tutorial. I’ll be using this technique throughout the rest of the article.

Creating a navigation template

As your project grows, you’ll need to add new pages to your style guide, which can be downright unmanageable if your navigation has to be updated across lots of files. With Handlebars, we can create a template and JavaScript file to handle our navigation markup:

I can then include a reference to my nav.js file in the HTML for the page. Any time I make changes to the JSON object in that file, it will be reflected across all pages in the style guide.

Managing the page content

For the actual page content, we’re going to create a new Handlebars template, but instead of putting our logic in a reusable JavaScript file, we’re going to put it on the page itself:

As you can see, there isn’t any markup for the content in page.html; instead, this is all served from the JSON object we defined and passed to our content template. Because we made sections an array, we can define multiple sections in our JSON object. I usually use the first section for the base of the component, and add additional ones for each modifier.

Conclusion

While I do think this technique works well for our particular situation, it might not work for every case. Here are some of the gotchas I’ve come across so far:

• Although it makes it easier, you still have to hand write your style guide using this technique. There is no link between your style guide and your code base, so if you make updates to the CSS or JS, you will need to manually add those changes to the style guide.

• This isn’t friendly to non-developers. This was fine in my case because this was specifically for developers, but it wouldn’t work well for broader style guides that are used between designers, developers, and project management.

• It can be tedious to format your code examples since you have to strip out the line breaks and any extra whitespace. As you can see in the page content example, I create a new line using \n. <script> tags also don’t work.

All this aside, I still think Handlebars is a nice solution for creating front-end style guides you can share with the rest of your development team. Throw this into Git and you can easily track changes and allow others to make updates alongside you.

If you’re interested in seeing a complete example or want to nab the code, check out my project over on GitHub.