Documenting your CSS with Styledown

Generating a styleguide for your CSS is something that can help other developers, and go a long way in reducing the confusion and possibility of someone reproducing the same styles. Ever jumped around a few projects over time and had to dive into all the CSS to find a style you thought was there, then found there was not one and you wrote it, or you may of even ended up duplicating some work that was brought up in a code review.

“Did you know we had a style already for that”

Generating a styleguide should not be a chore, and something you want your entire team to buy into. It should fit easily into your flow, not be too intimidating to other developers to start and continue with.

There are quite a lot of CSS styleguide generators around if you do a quick Google search, you will be greeted with many choices. I decided to go with styledown, as it looked to be the simplest and required very little in terms of getting up and running. Also the comments you needed to add to your CSS is very minimal, this suited what I was after. Another bonus for styledown was it was not Sass specific, it’s just CSS comments, you can even use markdown files if you so wish. Styledown is a node package, and is available on npm as styledown.

Documenting your CSS with Styledown is a simple as follows:

/***
 * Buttons:
 */
/**

Button:
button - Button stylings for default sbittons on the sitee

@example
button Standard button
*/

The first comment acts as the header, so in this case we are documenting our buttons. A file can contain multiple headers so you don’t have to worry too much about splitting your Sass up into lots of partials. We can then add comments throughout our CSS to give a description and example of the styles. The example part of the comment can be written as either Jade or HTML. The only required thing which can trip you up is the first line of the block you are documenting, in this case Button has to end with a semi-colon (:).

On top of adding comments to your CSS styledown allows you to have a config file, this file is markdown and lets you define what will be output in the head/body of the generated HTML file.

Generating the styleguide is as simple as running the following from your command line, assuming you have install the package globally.

styledown scss/**/*.scss config.md > index.html

If you are using gulp as your build tool you there is a gulp-styledown module, makes things nicer if you want to build the styleguide for each change. I recently added the gulp-styledown module to a new project and have the style guide generating on save of any .scss file.

I am running styledown on my little CSS framework I use for personal projects, it’s more a big reset and normalize in one. You can see the source on Github, or view the styleguide at flucss.com.