Module: kss

The core kss API can be imported with:

var kss = require('kss');

The main object is a function that will build a style guide given the correct options.

kss(options);

The various constructors and methods can then be accessed with:

const KssStyleGuide = require('kss').KssStyleGuide;
const KssSection    = require('kss').KssSection;
const KssModifier   = require('kss').KssModifier;
const KssParameter  = require('kss').KssParameter;

const kss           = require('kss');
const traverse      = require('kss').traverse();
const parse         = require('kss').parse();

The usual style guide build process:

  • The command-line tool uses lib/cli to gather the command line options, which passes the options to kss().
  • The kss() function takes an object of options and calls traverse().
  • The traverse() function reads all the source directories and calls parse().
  • The parse() function finds the KSS comments in the provided text, creates a JSON object containing all the parsed data and passes it the new KssStyleGuide(data) constructor to create a style guide object.
  • The kss() function loads the specified builder, which is a collection of files and an optional module that provides a sub-class of KssBuilderBase.
  • kss() passes its options to the builder the builder's addOptions() method.
  • The builder's prepare() method is given the KssStyleGuide object and can do any pre-build tasks, like initializing its templating system (if it has one.)
  • The builder's build() method is run and the style guide files are created in the specified destination.
Source:

Classes

KssModifier
KssParameter
KssSection
KssStyleGuide

Methods

(static) parse(input, optionsopt) → {KssStyleGuide}

Parse an array/string of documented CSS, or an array of file objects with their content.

Each File object in the array should be formatted as: { base: "path to source directory", path: "full path to file", contents: "content" }.

Parameters:
Name Type Attributes Description
input *

The input to parse
options Object <optional>

Options to alter the output content. Same as the options in traverse().
Source:
Returns:

Returns a KssStyleGuide object.

Type
KssStyleGuide

(static) traverse(directories, optionsopt) → {Promise}

Traverse a directory, parse its contents, and create a KssStyleGuide.

Callbacks receive an instance of KssStyleGuide.

If you want to parse anything other than css, less, sass, or stylus files then you'll want to use options.mask to target a different set of file extensions.

kss.traverse('./stylesheets', { mask: '*.css' }).then(function(styleGuide) {
  styleGuide.sections('2.1.1') // <KssSection>
});

There a few extra options you can pass to kss.traverse which will effect the output:

  • mask: Use a regex or string (e.g. *.less|*.css) to only parse files matching this value. Defaults to: *.css|*.less|*.sass|*.scss|*.styl|*.stylus
  • markdown: kss-node supports built-in Markdown formatting of its documentation, thanks to markdown-it. It's enabled by default, but you can disable it by adding markdown: false to the options object.
  • header: kss-node makes the header available separately from the description. To make kss-node behave like the Ruby KSS, disable this option and the title will remain a part of the description. This setting is enabled by default, but you can disable it by adding header: false to your options.
Parameters:
Name Type Attributes Description
directories String | Array

The directories to traverse
options Object <optional>

Options to alter the output content (optional)
Source:
Returns:

A Promise object resolving to a KssStyleGuide.

Type
Promise

(inner) kss(optionsopt) → {Promise.<(KssStyleGuide|null)>}

Builds a style guide given the proper options.

Parameters:
Name Type Attributes Description
options object <optional>

A collection of options.
Source:
Returns:

A Promise object resolving to a KssStyleGuide object, or to null if the clone option is used.

Type
Promise.<(KssStyleGuide|null)>