Getting Started with KSS-Node

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:

Jake Bresnehan

A Front End Developer based in Sydney and the creator of Web Design Weekly.

Web Design Weekly keeps developers at the forefront of techniques and trends whilst helping them learn and grow to produce top quality code to make the web a better place for all.

1 Comment

  1. 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!

This post currently has one response. What do you think?

You can use basic HTML when posting code, please turn all < characters into &lt; or > into &gt;
If the code is multi-line, use <pre><code></code></pre>

Leave a Reply

Your email address will not be published. Required fields are marked *

Current day month ye@r *