Gulp: living styleguides with node sassdown

This recipe will guide you through the installation and configuration of node-sassdown for live styleguide driven development.

Installation and Requirements

Install dependencies:

npm install node-sassdown --save-dev

Gulp tasks

Create a new file build/gulp-tasks/styleguide.js:

module.exports = function (gulp, $, options) {


    gulp.task('styleguide', function (done) {
        var Sassdown = require('node-sassdown');

        var srcGlob = '{*/*.scss}';
        var srcPath = options.assetsPath('src.sass');
        var destPath = options.paths.dist.root + '/styleguide/';
        
        var opts = {
            assets: [options.assetsPath('dist.css', '{styleguide,application}.css')],
            excludeMissing: true,
            readme: 'README.md',
            title: 'Living Styleguide',
            baseUrl: '/styleguide/'           
        };

        var sassdown = new Sassdown(srcGlob, srcPath, destPath, opts);

        sassdown.run(done);
    });

};

Then create application/assets/stylesheets/styleguide.scss. This file will be included in every auto-generated iframe with code examples.

For further customization see node-sassdown documentation

Workflow integration

Open build/gulp-config/properties.js and set property styleguideDriven to true.

Edit gulpfile.js adding adding before tasks.push(done); (line 104) the following lines:

if (options.styleguideDriven) {
    tasks.push('styleguide');
}

Finally , to enable styleguide rebuild on stylesheets' changes, edit build/gulp-tasks/serve.js and replace this lines:

gulp.watch([
    assetsPath('src.sass', '/**/*.{scss,sass}'),
    '!' + assetsPath('src.sass', '**/*scsslint_tmp*.{sass,scss}') //exclude scss lint files
], ['styles']);

with:

gulp.watch([
    assetsPath('src.sass', '/**/*.{scss,sass}'),
    '!' + assetsPath('src.sass', '**/*scsslint_tmp*.{sass,scss}') //exclude scss lint files
], (options.styleguideDriven ? ['styles', 'styleguide'] : ['styles']));