SC5 style guide generator

Looking for a maintainer

If you would like to maintain the project, create an issue and tell a few words about yourself.
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.

Usage
Documenting syntax
Designer tool
Images, fonts and other static assets
Tips and pointers
Demo
Additional Info
- Articles, blog posts
- Supplementary packages

Usage

You should familiarize yourself with both KSS
and node-kss to get yourself started.
SC5 Style guide provides additions to KSS syntax which you can learn below.

Prerequisites

The tool should be installed onto:

Node 4.2.x
Node 6.9.x

With Gulp

Install plugin locally:

npm install sc5-styleguide --save-dev

The Gulp plugin contains two functions that requires different set of file streams:
generate(): All unprocessed styles containing the KSS markup and style variables. This will process the KSS markup and collects variable information.
applyStyles(): Pre-processed/compiled style sheets. This will create necessary pseudo styles and create the actual style sheet to be used in the styleguide.
The following code shows complete example how to use styleguide with gulp-sass and with gulp watch.

var gulp = require('gulp');
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'
      }))
    .pipe(gulp.dest(outputPath));
});

gulp.task('styleguide:applystyles', function() {
  return gulp.src('main.scss')
    .pipe(sass({
      errLogToConsole: true
    }))
    .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.
If you do not use preprocessor you can directly pipe CSS files to applyStyles().
See Build options section for complete documentation of different options.

With Grunt

For projects using Grunt, install the plugin, Gulp and the grunt-gulp bridge.

npm install sc5-styleguide gulp 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-generate': function() {
      var outputPath = 'output';
      return gulp.src([''])
        .pipe(styleguide.generate({
            title: 'My Styleguide',
            server: true,
            rootPath: outputPath,
            overviewPath: 'README.md'
          }))
        .pipe(gulp.dest(outputPath));
    },
    'styleguide-applystyles': function() {
      return gulp.src('main.scss')
        .pipe(styleguide.applyStyles())
        .pipe(gulp.dest('output'));
    }
  },

  watch: {
    scss: {
      files: '**/*.scss',
      tasks: ['scss', 'gulp:styleguide-generate', 'gulp:styleguide-applystyles']
    }
  }
});

grunt.loadNpmTasks('grunt-gulp');

grunt.registerTask('default', ['gulp:styleguide-generate', 'gulp:styleguide-applystyles', 'watch']);

When using Grunt, we recommend processing styles in Grunt tasks as you do for your main application and pass
the resultant CSS into styleguide’s Gulp tasks.
For more specific documentation see the next section.

As a command line tool

This way of usage is not recommended, as it does not help as much with introduction of the styleguide into the day-to-day development process.
Install plugin globally:

npm install -g sc5-styleguide

Styleguide command line tool requires two sets of source files:
--kss-source: Unprocessed files containing the KSS markup and Less/Sass variables
--style-source Pre-processed/compiled style sheets to be used in the styleguide
Example usage:

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

You need to either specify a single directory or you can specify one or more source directories with one or more –kss-source flags.

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

Other options parameters are defined in the Build options section.

Build options

CLI and gulp options accept identically named parameters

title (string, optional)
This string is used as a page title and in the page header

favIcon (string, optional)
This enables to replace the default SC5 favicon. It takes path as a string.

extraHead (array or string, optional)
These HTML elements are injected inside the style guide head tag.

sideNav (boolean, optional, default: false)
Enables side navigation. When this option parameter is enabled, styleguide will switch to side navbar.

showReferenceNumbers (boolean, optional, default: false)
When this option parameter is enabled, style guide will show reference numbers on navigation, headings and designer tool.

includeDefaultStyles (boolean, optional, default: true)
Include/exclude default styles.

showMarkupSection (boolean, optional, default: true)
Show/hide Markup section.

hideSubsectionsOnMainSection (boolean, optional, default: false)
This option enables to prevent loading of subsections.

beforeBody (array or string, optional)
These HTML elements are injected inside the style guide <body> tag, before any other content.

afterBody (array or string, optional)
These HTML elements are injected inside the style guide <body> tag, after any other content.

afterSections (array or string, optional)
These HTML elements are injected inside the style guide .sg-body section, after any other content.

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.

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

port (number, optional)
Port of the server. Default is 3000.

disableServerLog (boolean, optional)
Disables embedded server log.

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.

appRoot (string, optional)
Define the appRoot parameter if you are hosting the style guide from a directory other than the root directory of
the HTTP server. If the style guide is hosted at http://example.com/styleguide the appRoot should be styleguide.
When using the build as a subdirectory of your application, tune your server to resolve all the paths to that subdirectory.
This allows Angular to deal with the routing. However, the static files should be resolved as they are stored.

styleVariables (string, optional)
By default variable definitions are searched from every file passed in gulp.src. styleVariables parameter could be used to filter from which files variables are loaded.

disableEncapsulation (boolean, optional, default: false)
Disable Shadow DOM encapsulation. When this option parameter is enabled, all styles are defined in page head and markup examples are not encapsulated using Shadow DOM.

disableHtml5Mode (boolean, optional, default: false)
Disable HTML5 URL mode. When this option parameter is enabled, style guide will use hash bang URLs instead of HTML5 history API. This is useful when hosting static style guides.

basicAuth (object, optional, default: null)
Protect server with basic HTTP authentication.

basicAuth: {
  username: 'username',
  password: 'password'
}

readOnly (boolean, optional, default: false)
Disable variable saving from web interface.

customColors (string, optional)
Path to file that defines custom UI color overrides using PostCSS variables. See all possible variables here.
Internal styles could be overridden by defining new styles inside the styleguide_custom_styles mixin. This mixin is added to the end of the application style sheet.
You can define your own styles with

@define-mixin styleguide_custom_styles {
  /* Define your styles here */
}

PostCSS configuration supports mixins, nesting, variables, media queries.

parsers (object, optional)
default:

parsers: {
  sass: 'scss',
  scss: 'scss',
  less: 'less',
  postcss: 'postcss'
}

Styleguide tries to guess which parser to use when parsing variable information from style sheets. The object key defines the file extension to match and the value refers to the parser name. There are three parsers available: scss, less and postcss.
For example, to parse all .css files using postcss parser, following configuration could be used:

{
  css: 'postcss'
}

styleguideProcessors (object,…