The NodeJS implementation of Knyle Style Sheets (KSS) developed by Hugh Kennedy is super handy. With one simple command after you have set it up you can generate a living style guide. Having to always update your style guide is generally a chore. This saves the day.
The purpose of KSS is to help you produce a HTML style guide tied to CSS documentation that is easy to read, yet structured enough to be automatically extracted and processed. It is designed with CSS preprocessors in mind and is flexible enough to accommodate a multitude of CSS frameworks.
Once you have Node installed, run the following command in your terminal
npm install -g kss
What this does is installs a global version of the KSS node package.
On completion of the KSS node package you are nearly ready to generate a “living style guide”.
Before going bananas on the command line, I would highly recommend checking out Hugh’s demo on GitHub. It offers some great examples and will no doubt save you some frustrating time trying to work out how you should structure your comments in your stylesheets.
The way KSS-Node works is it parses a directory of stylesheets and spits out a set of static HTML files.
Within your directory of stylesheets the node package will look for a styleguide.md file which will become the index of your generated style guide. This is referred to as the Overview Document.
One thing to keep in mind is that inside each stylesheet the comment at the top will help generate the navigation.
// Styleguide 1.1 //button.css
// Styleguide 2.1 //forms.css
This stumped me for a little while when setting it up, thankfully Hugh was super helpfully on twitter. Thanks Hugh! This is explained in grater detail on the index page of the demo.
Building Your Style Guide
Inside the terminal KSS-Node has the following format:
Usage:
kss-node sourcedir [destdir] --init [directory] --{style,less,sass,stylus} [file]
Options:
-t, --template Use a custom template to build your styleguide [string]
-s, --style Compile and include a stylesheet [string]
-l, --less Compile and include a LESS stylesheet [string]
-y, --stylus Compile and include a Stylus stylesheet [string]
-S, --sass Compile and include a SASS stylesheet [string]
-c, --css Compile and include a CSS stylesheet [string]
-m, --mask Use a custom mask for detecting stylesheets [string]
-i, --init Create a new styleguide template to work from
When you run the command you’ll need to specify a directory containing all of your CSS files to be parsed for documentation as the first argument. Optionally, the second argument can be used to specify a target directory. Your CSS won’t be included by default, hence you should use the –less, –css, etc. flags to point to a stylesheet to compile and include. You can generate a copy of the demo style guide like so:
$ kss-node demo styleguide --less demo/styles.less
Once you have run the above command you should have a new directory styleguide. Dig into it and work out how this awesome tool works.
Obviously this is just the tip of the iceberg of what KSS-Node can do. The GitHub repository will help you take things to the next level.
Happy documenting!
Resources:
Hey there! I’m at work surfing around your blog
from my new iphone! Just wanted to say I love reading your blog and look forward to all your posts!
Keep up the great work!