<commit_before># SC5 style guide generator
[![Build Status](https://travis-ci.org/SC5/sc5-styleguide.svg?branch=master)](https://travis-ci.org/SC5/sc5-styleguide) [![dependencies](https://david-dm.org/SC5/sc5-styleguide.png)](https://david-dm.org/SC5/sc5-styleguide)

Style guide generator is a handy little tool that helps you generate good looking style guides from style sheets
using KSS notation. It can be used as a command line utility, gulp task or grunt task (needs grunt-gulp) with minimal effort.

## Table of contents

* [Usage](#usage)
  * [As a command line tool](#as-a-command-line-tool)
  * [As a module in your project](#as-a-module-in-your-project)
    * [With Gulp](#with-gulp)
    * [With Grunt](#with-grunt)
  * [Build options](#build-options)
* [Documenting syntax](#documenting-syntax)
  * [Wrapper markup](#wrapper-markup)
* [Designer tool](#designer-tool)
* [Tips and pointers](#tips-and-pointers)
* [Demo](#demo)

## Usage

You should familiarize yourself with both [KSS](https://github.com/kneath/kss)
and [node-kss](https://github.com/kss-node/kss-node) to get yourself started.

SC5 Style guide provides additions to KSS syntax which you can learn [below](#user-content-documenting-syntax).

### As a command line tool

Installing as a global command line tool

    npm install -g sc5-styleguide

Styleguide command line tool needs two sets of source files, unprocessed files that contain KSS and preprocessed CSS files. KSS files are defined using the `--kss-source` options and preprossed files using the `--style-source` option. Target directory is defined using the `--output` option.

Example usage:

    styleguide --kss-source "sass/*.scss" --style-source "public/*.css" --output styleguide --watch --server

Other options parameters are defined in the [Build options](#build-options) section.

### Using styleguide as a gulp plugin

Installing as a gulp plugin

    npm install sc5-styleguide --save-dev

There are two public functions that are used to generate the styleguide, `generate` and `applyStyles`. All unprocessed styles should be piped to `generate` function that will process the KSS markup and variable infromation. Preprocessed styles should piped to `applyStyles` function. This will create necessary pseudo styles and create the actual stylesheet to be used in the styleguide.

This approach gives flexibility to use any preprocessor. For example, you can freely replace gulp-sass with gulp-ruby-sass. However, please notice that variable parsing work only for SASS, SCSS and LESS files.

The following code shows complete example how to use styleguide with using gulp-sass as a preprocessor and with live-reload ability using gulp watch.

    var styleguide = require('sc5-styleguide');
    var sass = require('gulp-sass'),
    var outputPath = 'output';

    gulp.task('styleguide:generate', function() {
      return gulp.src('*.scss')
        .pipe(styleguide.generate({
            title: 'My Styleguide',
            server: true,
            rootPath: outputPath,
            overviewPath: 'README.md',
            styleVariables: 'lib/app/sass/_styleguide_variables.scss'
          }))
        .pipe(gulp.dest(outputPath));
    });

    gulp.task('styleguide:applystyles', function() {
      return gulp.src('main.scss')
        .pipe(sass())
        .pipe(styleguide.applyStyles())
        .pipe(gulp.dest(outputPath));
    });

    gulp.task('watch', ['styleguide'], function() {
      // Start watching changes and update styleguide whenever changes are detected
      // Styleguide automatically detects existing server instance
      gulp.watch(['*.scss'], ['styleguide']);
    });

    gulp.task('styleguide', 'styleguide:generate', 'styleguide:applystyles']);

For more specific documentation. See [Build options](#build-options) section.

### With Grunt

For Grunt-using projects you need to use `grunt-gulp` bridge:

    npm install grunt-gulp --save-dev

Then you are able to use the same gulp task inside you `Gruntfile`:

    var gulp = require('gulp'),
      styleguide = require('sc5-styleguide');

    grunt.initConfig({
      pkg: grunt.file.readJSON('package.json'),
      gulp: {
        styleguide: function() {
          var outputPath = 'output';
          return gulp.src([''])
            .pipe(styleguide.generate({
                title: 'My Styleguide',
                server: true,
                rootPath: outputPath,
              }))
            .pipe(gulp.dest(outputPath));
        }
      }
    });

    grunt.loadNpmTasks('grunt-gulp');

    grunt.registerTask('default', ['gulp']);

For more specific documentation. See next section.

### Build options

The gulp function and configuration JSON accepts identically named parameters

<a name="option-title"></a>
**title** (string, optional)

This string is used as a page title and in the page header

<a name="option-extraHead"></a>
**extraHead** (array or string, optional)

These HTML elements are injected inside the style guide head-tag.

<a name="option-commonClass"></a>
**commonClass** (string or array of strings, optional)

The provided classes are added to all preview blocks in the generated style guide.
This option is useful if you have some namespace classes that should to be added to every block, but you do not want to add it to every example section's markup.

<a name="option-server"></a>
**server** (boolean, optional)

Enable built-in web-server. To enable Desiger tool the style guide must be served with the built-in web server.
The server has also ability to refresh changed styles or KSS markup without doing a full page reload.

<a name="option-port"></a>
**port** (number, optional)

Port of the server. Default is 3000.

<a name="option-rootPath"></a>
**rootPath** (string, optional)

Server root path. This must be defined if you run the built-in server via gulp or grunt task.
Point to the same path as the style guide output folder.

**Note**: This option is not needed when running styleguide via the CLI.

<a name="option-appRoot"></a>
**appRoot** (string, optional)
<commit_msg>Improve README<commit_after># SC5 style guide generator
[![Build Status](https://travis-ci.org/SC5/sc5-styleguide.svg?branch=master)](https://travis-ci.org/SC5/sc5-styleguide) [![dependencies](https://david-dm.org/SC5/sc5-styleguide.png)](https://david-dm.org/SC5/sc5-styleguide)

Style guide generator is a handy little tool that helps you generate good looking style guides from style sheets
using KSS notation. It can be used as a command line utility, gulp task or grunt task (needs grunt-gulp) with minimal effort.

## Table of contents

* [Usage](#usage)
  * [As a command line tool](#as-a-command-line-tool)
  * [With gulp](#with-gulp)
  * [With grunt](#with-grunt)
  * [Build options](#build-options)
* [Documenting syntax](#documenting-syntax)
  * [Wrapper markup](#wrapper-markup)
* [Designer tool](#designer-tool)
* [Tips and pointers](#tips-and-pointers)
* [Demo](#demo)

## Usage

You should familiarize yourself with both [KSS](https://github.com/kneath/kss)
and [node-kss](https://github.com/kss-node/kss-node) to get yourself started.

SC5 Style guide provides additions to KSS syntax which you can learn [below](#user-content-documenting-syntax).

### As a command line tool

Install plugin globally:

    npm install -g sc5-styleguide

Styleguide command line tool required two sets of source files:

`--kss-source`: Unprocessed files containing the KSS markup

`--style-source` Preprosessed/compiled stylesheets applied as actual styles

Example usage:

    styleguide --kss-source "sass/*.scss" --style-source "public/*.css" --output styleguide --watch --server

Other options parameters are defined in the [Build options](#build-options) section.

### With gulp

Installing as a gulp plugin

    npm install sc5-styleguide --save-dev

The gulp plugin contains two functions that requires different set of files:

`generate()`: All unprocessed styles containing the KSS markup. This will process the KSS markup and collects variable infromation.

`applyStyles()`: Preprocessed/compiled stylesheets should. This will create necessary pseudo styles and create the actual stylesheet to be used in the styleguide.

The following code shows complete example how to use styleguide with using gulp-sass as a preprocessor and with live-reload ability using gulp watch.

    var styleguide = require('sc5-styleguide');
    var sass = require('gulp-sass'),
    var outputPath = 'output';

    gulp.task('styleguide:generate', function() {
      return gulp.src('*.scss')
        .pipe(styleguide.generate({
            title: 'My Styleguide',
            server: true,
            rootPath: outputPath,
            overviewPath: 'README.md',
            styleVariables: 'lib/app/sass/_styleguide_variables.scss'
          }))
        .pipe(gulp.dest(outputPath));
    });

    gulp.task('styleguide:applystyles', function() {
      return gulp.src('main.scss')
        .pipe(sass())
        .pipe(styleguide.applyStyles())
        .pipe(gulp.dest(outputPath));
    });

    gulp.task('watch', ['styleguide'], function() {
      // Start watching changes and update styleguide whenever changes are detected
      // Styleguide automatically detects existing server instance
      gulp.watch(['*.scss'], ['styleguide']);
    });

    gulp.task('styleguide', 'styleguide:generate', 'styleguide:applystyles']);

This approach gives flexibility to use any preprocessor. For example, you can freely replace gulp-sass with gulp-ruby-sass. However, please notice that variable parsing works only for SASS, SCSS and LESS files.

See [Build options](#build-options) section for complete documentation of different options.

### With grunt

Install the plugin first:

    npm install sc5-styleguide --save-dev

For Grunt-using projects you need also `grunt-gulp` bridge:

    npm install grunt-gulp --save-dev

Then you are able to use the same gulp task inside you `Gruntfile`:

    var gulp = require('gulp'),
      styleguide = require('sc5-styleguide');

    grunt.initConfig({
      pkg: grunt.file.readJSON('package.json'),
      gulp: {
        styleguide: function() {
          var outputPath = 'output';
          return gulp.src([''])
            .pipe(styleguide.generate({
                title: 'My Styleguide',
                server: true,
                rootPath: outputPath,
              }))
            .pipe(gulp.dest(outputPath));
        }
      }
    });

    grunt.loadNpmTasks('grunt-gulp');

    grunt.registerTask('default', ['gulp']);

For more specific documentation. See next section.

### Build options

CLI and gulp otpions accepts identically named parameters

<a name="option-title"></a>
**title** (string, optional)

This string is used as a page title and in the page header

<a name="option-extraHead"></a>
**extraHead** (array or string, optional)

These HTML elements are injected inside the style guide head-tag.

<a name="option-commonClass"></a>
**commonClass** (string or array of strings, optional)

The provided classes are added to all preview blocks in the generated style guide.
This option is useful if you have some namespace classes that should to be added to every block, but you do not want to add it to every example section's markup.

<a name="option-server"></a>
**server** (boolean, optional)

Enable built-in web-server. To enable Desiger tool the style guide must be served with the built-in web server.
The server has also ability to refresh changed styles or KSS markup without doing a full page reload.

<a name="option-port"></a>
**port** (number, optional)

Port of the server. Default is 3000.

<a name="option-rootPath"></a>
**rootPath** (string, optional)

Server root path. This must be defined if you run the built-in server via gulp or grunt task.
Point to the same path as the style guide output folder.

Note: This option is not needed when running styleguide via the CLI.

<a name="option-appRoot"></a>
**appRoot** (string, optional)

{'fraction_non_alphanumeric': 0.11247597559956547, 'fraction_numerical': 0.0030918358820088577, 'mean_word_length': 3.6155032780563054, 'pattern_counts': {'":': 0, '<': 31, '<?xml version=': 0, '>': 31, 'https://': 12, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4950592', 'n_tokens_mistral': 3568, 'n_tokens_neox': 3495, 'n_words': 1260}