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.
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;
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
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
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.
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
<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.