Universal CSS styleguide generator for grunt
| Framework | Preprocessor | Templates |
|---|---|---|
| styledocco | LESS, SASS | Default template providd by styldocco is used |
| Framework | Preprocessor | Templates |
|---|---|---|
| JSS-Styles | None | Template can be configured to include files post compile |
Athough there is no preprocessor support files can stil be processed and documentation generated. Use the template include option to add references of the compiled CSS to the guide.
- node-kss (v0.3.0)
If you haven't used grunt before, be sure to check out the Getting Started guide.
From the same directory as your project's Gruntfile and package.json, install this plugin with the following command:
npm install grunt-styleguide --save-devOnce that's done, add this line to your project's Gruntfile:
grunt.loadNpmTasks('grunt-styleguide');If the plugin has been installed correctly, running grunt --help at the command line should list the newly-installed plugin's task or tasks. In addition, the plugin should be listed in package.json as a devDependency, which ensures that it will be installed whenever the npm install command is run.
In your project's Gruntfile, add a section named styleguide to the data object passed into grunt.initConfig().
grunt.initConfig({
styleguide: {
options: {
// global options
},
your_target: {
options: {
// task options
},
files: {
// files to process
}
}
}
})
By default grunt-styleguide will attempt to rationalize options for each of the styleguide frameworks supported depending upon the features available to the framework in use.
| Key | Type | Required | Description |
|---|---|---|---|
| framework | String, object, function (*) | No | Details about the styleguide framework |
| name | String | No | Title of the styleguide |
| template | Object | No | Details of the templetes to use for rendering if supported |
Should you wish to pass additional options a framework supports these can be passed as options as part of the framework object.
styleguide: {
dist: {
options: {
framework: {
name: 'framework_name',
options: {
'somearg': 'somevalue',
'someflag: true
}
}
},
files: {
'path/to/dest': 'path/to/source'
}
}
}
Depending upon the framework, it may be possible to also pass templates to use for rending a styleguide.
styleguide: {
dist: {
options: {
template: {
src: ['path/to/templates'],
include: ['path/of/resources/to/include'],
mapping: {
'layout': 'some_template_name',
'styleguide': 'some_template_name'
}
}
files: {
'path/to/dest': 'path/to/source'
}
}
}
}
| Key | Type | Required | Description |
|---|---|---|---|
| src | String, Array | No | Location of the templates to use |
| name | String, Array | No | Title of the styleguide |
| mapping | Object | Depends on templates | Define what templates should be used for rendering a styleguide |
By default grunt-styleguide will determine the CSS preprocessor to use by evaluating the selected source files. This value will be passed as an option to framework and if supported will be used by it.
In this example a styleguide will be generated using the default generator, styledocco. Guides will be created for css/scss located within the core and plugins directory and output them to the appropriate destination specified.
grunt.initConfig({
styleguide: {
dist: {
files: {
'docs/core': 'stylesheets/sass/core/*.scss',
'docs/plugins': 'stylesheets/sass/plugins/*.scss',
}
}
}
});
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using grunt.
- Revised documentation
- Added JSS-Styles support
- Revised options structure
- Introduced template options
- Travis support
- Grunt compatibility tweaks
- Initial Release