Skip to content

Quick Start Guide

Jump to bottom Edit New page
Scheibo edited this page Jan 25, 2019 · 21 revisions

kss is easy to use and easy to set up. All you need is some CSS (or Sass or LESS or Stylus…) and some HTML. Oh, and Node.js' npm command.

If you've never used Node.js, you should read the npm Quick Start Guide. Feel free to skip over the bits you already know. But the "Installing kss-node" section won't make sense until you are familiar with npm.

Read the The npm Quick Start Guide

Installing kss-node

Now that your project has a package.json and you've set up your Bash command prompt to easily run local node modules, you can install kss-node with:

$ npm install --save-dev kss

IMO, that's the only way you should ever install kss-node. If you still think you should install kss-node with npm install -g kss, go back and read the npm primer, as using the -g option will cause you problems if you have 2 or more different projects using kss-node.

You can verify kss-node was installed correctly by using npm-run:

$ npm-run kss --help

Or ./node_modules/.bin/kss --help instead of npm-run.

Adding KSS comments

It's super easy to add KSS comments. For example:

// Hard rules
//
// Style guide: hard-rule
hr {
  border-top: 5px solid #999;
}

That's the simplest KSS comment, but you can learn more about the KSS syntax by reading the annotated KSS spec that includes kss-node extras.

Running kss-node

You're finally ready to generate a style guide!

$ npm-run kss --source path/to/css-or-sass-etc --destination styleguide --css url/to/css-file

kss will parse your --source files and generate a static set of HTML files into the --destination folder, including a <link> to your project's --css file.

Running kss-node < v3.0.0

$ npm-run kss-node --source path/to/css-or-sass-etc --destination styleguide --css url/to/css-file

Running kss-node repeatedly

All of those command line options can get pretty annoying. So kss-node has the ability to read all of the options from a JSON file.

$ npm-run kss --config path/to/kss-config.json

or prior to version 3.0.0

$ npm-run kss-node --config path/to/kss-config.json

Here's an example config file:

{
  "//": "The source and destination paths are relative to this file.",
  "source": [
    "sass",
    "bower_components"
  ],
  "destination":  "styleguide/",

  "//": "The css and js paths are URLs relative to the generated style guide.",
  "css": [
    "../css/styles.css",
    "../css/even-more-styles.css"
  ],
  "js": [
  ]
}

You can see a list of all the command line options (which can be put in the kss-config.json file without the --) by typing:

$ npm-run kss --help

or with versions prior to 3.0.0

$ npm-run kss-node --help

Integration with Gulp or Grunt

There's an active discussion about this subject in the kss-node issue queue.

Changing the look of your style guide

When kss generates a style guide, it uses a default builder – prior to 3.0.0 they where called templates – that looks for Handlebars .hbs files for its HTML source.

If you don't like the way the style guide looks, you have a few options:

  1. Help make the default builder look better. Seriously, we could use some help and it's not that hard!
  2. Create a clone of the default builder with npm-run kss --clone (< 3.0.0 npm-run kss-node --init) which will create a copy of the default builder in a new custom-builder folder. You can then edit those template files and tell kss to use your new builder with npm-run kss --builder path/to/custom-builder (< 3.0.0 npm-run kss-node --template path/to/custom-builder).
  3. Find a 3rd-party kss-node builder to use. Some example for kss-node versions prior 3.0.0 (they might not work with the latest version).

Sharing your results

Have a nice looking publicly-available style guide built with kss-node? Share your results on the KSS style guide examples page.

Add a custom footer
Clone this wiki locally