grunt-emo (Beta)

A style-guide generator that uses Swig.js

Emo is a tool that scrapes documention from your source files which it then uses to generate a style-guide. Emo is capable of gathering documention from, essentially, any type of file, which allows you to easily document your JavaScript, HTML, or whatever other type of component that you'd like documented.

Getting Started

This plugin requires Grunt ~0.4.5

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-emo --save-dev

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

grunt.loadNpmTasks('grunt-emo');

The "emo" task

Overview

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

grunt.initConfig({
    emo: {
        main: {
            options: {
                path: { ... },
                copy: {
                    'assets/css/modern.css': 'web/assets/css/modern.css'
                }
            },
            files: [
                {
                    expand: true,
                    cwd: '',
                    src: [
                        'assets/scss/**/*.scss',
                        'assets/scss/**/*.less',
                        'assets/css/**/*.css'
                    ]
                }
            ]
        }
    }
});

Options

options.path

Type: Object Default value: { src: '_styleguide/', dest: 'docs/styleguide/' }

Paths used by the style-guide generator

options.path.src

Type: String Default value: _styleguide/

The location the styleguide source code is to be placed. Must include a trailing slash.

options.path.dest

Type: String Default value: docs/styleguide/

The location the styleguide will be built to. Must include a trailing slash.

options.copy

Type: Object Default value: undefined

An object containing assets that should be copied over to the style-guide destination folder.

Note the example below. The right hand assignment is the path to the asset that should be copied; the left hand assignment is the path to where the asset should be copied to within the style-guide destination folder.

grunt.initConfig({
    emo: {
        main: {
            options: {
                copy: {
                    'assets/css/modern.css': 'web/assets/css/modern.css'
                }
            }
        }
    }
});

Usage Examples

Default Options

grunt.initConfig({
    emo: {
        main: {
            options: {
                copy: {
                    'assets/css/modern.css': 'web/assets/css/modern.css'
                }
            },
            files: [
                {
                    expand: true,
                    cwd: '',
                    src: [
                        'assets/scss/**/*.scss'
                    ]
                }
            ]
        }
    }
});

Custom Options

Below, emo is configured to output the style-guide as well as its source in a custom location.

grunt.initConfig({
    emo: {
        main: {
            options: {
                path: {
                    src: 'some/path/',
                    dest: 'styleguide/'
                },
                copy: {
                    'assets/css/modern.css': 'web/assets/css/modern.css'
                }
            },
            files: [
                {
                    expand: true,
                    cwd: '',
                    src: [
                        'assets/scss/**/*.scss'
                    ]
                }
            ]
        }
    }
});

Documentation Syntax

Emo searches for name/value combinations within your source files; these name/value combinations are then used within the component.html Swig template. Note that all values are parsed as markdown. Name/value combinations are expected to take the following format.

/*

    {% Name: Btn %}

    {% Category: elements %}

    {% Description: <button>I'm a button</button> %}

*/

.btn {
    color: blue;
}

Specifically, each name/pair value is expected to be enclosed within {%%} markings and separated by a :. As components can be lengthy, it's not always ideal to inline documenation in your CSS/SCSS/LESS files. As such, emo allows you to load documentation from markdown files.

/*

    {% Name: Btn %}

    {% Category: elements %}

    {% Description: relative/path/to/markdown-file.md %}

*/

.btn {
    color: blue;
}

As previously mentioned, emo can accept any number of name/value combinations, though it demands that name, category and description are used. Each name/value combination is available within the generated Swig templates via the component global. Use name/value combinations as you wish.

/*

    {% Name: Btn %}

    {% Category: elements %}

    {% Version: 1.0.0 %}

    {% Author: Michael Jordan %}

    {% Description: relative/path/to/btn_docs.md %}

*/

.btn {
    color: blue;
}

The previous examples show name/value combinations within CSS comments. Emo is capable of scraping documention from within all comment types:

//-------------------------------------------------
// Btn
//-------------------------------------------------
//
//  {% Name: Btn %}
//
//  {% Category: elements %}
//
//  {% Version: 1.0.0 %}
//
//  {% Author: Michael Jordan %}
//
//  {% Description: relative/path/to/btn_docs.md %}
//
//-------------------------------------------------

.btn {
    color: blue;
}

<!--

    {% Name: Btn %}

    {% Category: elements %}

    {% Description: <button class="btn">Im' a button</button> %}

-->

<button class="btn">Im' a button</button>

Categories

Emo was inspired by pattern lab, which categorizes UI components as atoms, molecules, organisms, templates, and pages. Emo uses a similar set of categories: elements, molecules, and organisms. In order for a component to show up in the generated style-guide, it must be placed in one of these categories.

Elements

See atoms

Molecules

See molecules

Organisms

See organisms

Contributing

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.

Release History

(Nothing yet)