StyleDocco: Style Sheets to Style Guide

CSS Style Guide

Author :  

CSS Style Guide

If you work alone or in a group, it’s important to remain consistent. Writing documentation and style guides, however, takes up a lot of time. Thankfully, there’s a plugin for that called StyleDooco that can do just that. The plugin takes the comments in a CSS file and generates an HTML file. The plugin requires you to install NodeJS. There’s also a Grunt plugin that you can use for your projects; you can also find the project on GitHub. Let’s take a look at the Grunt plugin and how to install and configure it for your project.


Let’s take a look at what the plugin actually does. If you have a CSS file, such like this:


Then, it will take the CSS, pass it through Markdown and then export it as an HTML file like so:

The documentation created by the plugin

Here’s another example:

The documentation for StyleDocco

Let’s try it out!

Installing NodeJS

Install NodeJS

You will need to download and install NodeJS first.

Installing and Using with Grunt

Installing Grunt is simple, all you need to do is run this command in Terminal:

The npm is Node’s package manager tool, install is the command, -g is a flag used to install the Node package globally on your machine. This means that you will be able to run the command anywhere. Finally, grunt-cli is the name of the node package. Run the following commands to create a new folder on your desktop, change into the directory and to install the plugin.

If you get an error message, you can just add the sudo command:

For this tutorial, I have downloaded Foundation and moved the CSS files from Foundation over to test/css. Here’s what my directory structure looks like:

Directory Structure for test


This is what should go inside the Gruntfile.js:

You can use either Sublime Text 2 or VIM in order to add the following code to the top of your css file. Here’s an example:


Note: When using styledocco, spaces are important. Whatever you do, don’t use tabs, use spaces! Otherwise, the page/elements might break!

What you are looking at is, in essence, a CSS comment. However, thanks to styledocco, you can use Markdown. When styledocco compiles, it will take the CSS comment, parse the Markdown and create a brand new HTML document. In this case, it will create a docs folder. Be sure to save you file.

Now you just need to run the grunt command and it should create a new doc folder.

You should see the following


If everything has gone as planned, then you should see the new docs folder as well as two HTML files.


If everything has gone as planned then you should see a new folder apear


In the end, the newly generated HTML page should look something like this:

What the generated html shou

Here’s what it looks like in the CSS file:

Everything should now be set up and ready to go. If you have any questions, feel free to leave a comment below.