Creates a custom styleguide from (commented) CSS files.
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');
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.
},
},
});
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.
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.
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!
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' ],
},
},
});
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.
Note: Still under active development with no official release, use at your own risk.
0.2.2
0.2.1
source_path
option.0.2.0
0.1.0