grunt-custom-styleguide

Creates a custom styleguide from (commented) CSS files.

Getting Started

This plugin requires Grunt ~0.4.2

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-custom-styleguide --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-custom-styleguide');

The "custom_styleguide" task

Overview

In your project's Gruntfile, add a section named custom_styleguide to the data object passed into grunt.initConfig().

grunt.initConfig({
  custom_styleguide: {
    options: {
      // Task-specific options go here.
    },
    your_target: {
      // Target-specific file lists and/or options go here.
    },
  },
});

Options

options.processor

Type: String or Object Default value: markdown

Specifies the processer to use. Either provide a string matching the name of one of the registered processors (currently the only built-in processor is 'markdown') or provide a javascript object. In this object you can either define your own process function and any helper function you like or override functions of built-in processors (use in conjunction with inheritFromBuiltInProcessor option). See examples below.

options.inheritFromBuiltInProcessor

Type: String Default value: ``

Name of one of the built-in processors that should be extended by the object you provided using the processor option.

options.source_path

Type: String Default value: ``

Using the source_path parameter you can set the base path for all the stylesheet dependencies. This is useful, when you have your stylesheets in special subdirectory (e.g. a source or build output directory). When defining the files array, you can then provide the filenames relative to this directory and the processor's process function will provide you these relative filenames instead of a filepath where you would have to remove some parts. Working on an example to demonstrate this!

Usage Examples

Markdown processor example

Basic example demonstrating the use of build-in processors.

grunt.initConfig(
{
  custom_styleguide:
  {
    options:
    {
      processor: 'markdown'
    },
    files:
    {
      'styleguide.html': [ 'path/to/style.css', 'path/to/advanced-style.css' ],
    },
  },
});

Custom processor example

In this example, a custom processor is provided to the task. This gives you full control on how your styleguide is generated. If you think that other might be interested in your styleguide processor, please create a pull request.

grunt.initConfig(
{
  custom_styleguide:
  {
    options:
    {
      processor:
      {
        process: function(stylesheets, outputPath)
        {
          // stylesheets is an object. Each key-value pair consists of
          // the stylesheet filename (key) and the an array of all rules (value)
          // found in the stylesheet file.

          var rules = this.getRulesFromStylesheets(stylesheets);

          // you can do any kind of processing and file handling here
          grunt.file.write(outputFile, JSON.stringify(rules, null, 2));
        },

        getRulesFromStylesheets: function(stylesheets)
        {
          var allRules = [];

          // grab all rules from the stylesheets
          for (var sheet in stylesheets)
          {
            var rules = stylesheets[sheet].rules;

            rules = rules.map(function(rule)
            {
              rule.stylesheet = sheet;
              return rule;
            });

            allRules = allRules.concat(rules);
          }

          return allRules;
        }

      },
      inheritFromBuiltInProcessor: 'markdown'
    },
    files:
    {
      'styleguide.html': [ 'path/to/style.css', 'path/to/advanced-style.css' ],
    },
  },
});

Note: I will add more examples shortly.

Release History

Note: Still under active development with no official release, use at your own risk.

0.2.1

• Added source_path option.

0.2.0

• Refactored custom_styleguide task to make it as flexible as possible. You can now use built-in processors, extend them partially or provide your own.

0.1.0

• Defined custom_styleguide task.