antoniozzo/kraftverk

Styleguide generator with KSS

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
}

kraftverk's Issues

Question: Is it possible to to pass inline objects to templates?

Would be handy in some cases to actually be able to pass inlined objects as the value to component templates for quick and easy mocking.

For example:
{{> components.article links="{title: 'Lorem', href='#'}"}}

Feature Request: Include svg sprite in compiled html template

When using svg sprites, Internet Explorer needs the svg sprite to be printed to the document where the href value instead of being the complete path to the sprite just passes the id to the desired symbol.

Does not work in IE:

Does work in IE:

Feature Request: Custom property to set the initial viewport size of iframes

This would be handy to have for example when a component is meant to be used side by side in a grid to show it's intended size. This would also save scroll distance.

SVG and icons linking possibility.

Add the ability to include a path to svg:s and icons.
Right now we have to change the path in the icon component to make it work.

Maybe add a codeblock in the beginning of the body, where we can include what whatever.

Bug: Font-size inside iframes incorrectly upscaled on page-load.

Very frequently on page-loads, the font-size inside the styleguide's iframes is incorrectly upscaled. This jumps back to the correct font-size if one toggles the different viewports; mobile, tablet, desktop.