Kraftverk

Kraftverk is a style guide generator. Kraftverk uses KSS for parsing CSS comments to later generate a beautiful style guide with alot of useful features.

Table of contents

• Usage
  • CLI
  • With Gulp
• Options
  • Kraftverk Options
  • Theme Options
• Default Theme
  • Custom Properties
    • Examples
      • Template
      • Transparent

Usage

First you should read up on the KSS documentation & syntax.

CLI

Currently Kraftverk does not work as a CLI.

With gulp

Kraftverk has a gulp plugin:

npm install gulp-kraftverk --save-dev

In your gulpfile.js:

var gulp      = require('gulp');
var kraftverk = require('gulp-kraftverk');

gulp.task('kraftverk', function() {
	return gulp.src('src/css/**') // or LESS/SASS/SCSS etc...
		.pipe(kraftverk(/* options */))
		.pipe(gulp.dest('styleguide/'));
});

Options

Kraftverk Options

Option | Type | Default Value | Description --- | --- | --- | --- title | string | "Styleguide" | The main title of your style guide static site. theme | string | "/theme" | Path to the style guide theme. styles | array | [] | Array of stylesheets to be included in your site examples. scripts | array | [] | Array of scripts to be included in your site examples. templates | string | "src/templates" | Path to the handlebars templates for external markup. docs | object | | Documentation options docs.dir | string | "src/docs" | Path to markdown doc files. docs.title | string | "Documentation" | Title of the docs home page. docs.index | string | "index.md" | Path to the home page relative to the docs.dir.

Theme Options

Option | Type | Default Value | Description --- | --- | --- | --- depth | integer | 2 | How deep in the KSS hierarchy to generate unique style guide pages. assets | string | "assets" | Relative path to the theme's assets. partials | string | "partials" | Relative path to the theme's handlebars partials. helpers | string | "helpers.js" | Relative path to the theme's handlebars helpers file. custom | array | ['Template', 'Transparent'] | Custom comment properties used in the theme.

Default Theme

Custom Properties

The default kraftverk theme supports additional comment properties besides the ones in KSS.

Option | Type | Default Value | Description --- | --- | --- | --- Template | docs/example/colors | dynamic | Template used for documenting you KSS comment. Kraftverk theme try to guess your prefered template between docs and example depending of you having a Markup: in your KSS comment or not. Transparent | true/false | true | Force the iframe (used for displaying examples) background to transparent. Useful for when you want to showcase single components vs. complete page templates. Defaults to true since it's more common to display smaller components by themself.

Examples

All examples are using LESS.

Template

Display your color variables in the style guide:

// Colors
//
// @red  - #ff6666
// @blue - #6666ff
//
// Template: colors
//
// Styleguide: variables.colors

@red  : #ff6666
@blue : #6666ff

Transparent

Use your site background in the style guide example (useful for showcasing pages):

// Home
//
// Markup: pages/home.hbs
//
// Transparent: false
//
// Styleguide: pages.home

.home {
    // styles
}