grunt-atomizer/README.md

Grunt task for Atomizer

# grunt-atomizer [![npm version](https://badge.fury.io/js/grunt-atomizer.svg)](http://badge.fury.io/js/grunt-atomizer)

## Overview

A grunt task for running [Atomizer](http://github.com/acss-io/atomizer)

## Install

```bash
npm install grunt-atomizer --save-dev
```

## Usage

### Options

None of the options are required. Make sure you understand [atomic configs](https://github.com/acss-io/atomizer/blob/master/examples/example-config.js) in order to properly use the config options below.

#### options.cache

Caches the output of the task target by saving it to `.atomic-cache` at the root dir. False by default.

#### options.config

The [Atomizer](http://github.com/acss-io/atomizer) config passed directly to the grunt task. See examples below.

#### options.configFile

The [Atomizer](http://github.com/acss-io/atomizer) config passed as a file. This option can be used as an alternative to `options.config` or in conjunction with it. See examples below.

#### options.configOutput

The config file generated by the tool. Useful when parsing is used (See `files.src` below) and you want to save generated config.

#### options.bumpMQ

Boolean flag that adds a small amount of additional specificity weight to all media queries. False by default.

#### options.namespace

A CSS selector used to define scope for the Atomic CSS rules.  (eg, if `options.namespace` is set to `#atomic`, the CSS output will be in the form of `#atomic .P(10px)`, etc.)

#### options.rtl

Process the rules for right-to-left output. False by default.

#### options.rules

An array of additional [Atomizer](http://github.com/acss-io/atomizer) rulesets passed as file paths. 

#### files.src

Any files matched by `files.src` will be parsed and if valid atomic classes are found they will be added to the final CSS. You'd generally want to also pass a `options.configOutput` so that you have the updated config. Custom class names cannot be automatically generated and have to be manually added in the config.

#### files.dest

The path to the CSS file that will be created.

### Examples

```javascript
atomizer: {
    // Example 1: Simple usage. Parse files and create CSS.
    // Ideally you'd also want to pass a namespace to deal with specificity.
    example1: {
        files: [
            {
                src: ['test/fixtures/*.html'],
                dest: 'tmp/configFileOnly.css'
            }
        ]
    },
    // Example 2: Passing a configFile only.
    example2: {
        options: {
            namespace: '#atomic',
            configFile: 'test/fixtures/sample-config.js'
        },
        files: [
            {
                dest: 'tmp/configFileOnly.css'
            }
        ]
    },
    // Example 3: Passing the config to the grunt task directly
    example3: {
        options: {
            namespace: '#atomic',
            config: {
                classNames: ['D(ib)']
            }
        },
        files: [
            {
                dest: 'tmp/configGruntOnly.css'
            }
        ]
    },
    // Example 4: Using both config and configFile.
    // `options.config` will be merged (and override) the `options.configFile`.
    example4: {
        options: {
            namespace: '#atomic',
            // bring a sample config file
            configFile: 'test/fixtures/sample-config.js',
            // config will override any thing declared in configFile
            config: {
                classNames: ['D(ib)'],
                custom: {
                    '1': '10px solid #ccc'
                }
            }
        },
        files: [
            {
                dest: 'tmp/configBoth.css'
            }
        ]
    },
    // Example 5: Using config, configFile and also parsing HTML files (it can be any type of file).
    // Parsing will warn if you've used a class that cannot be automatically generated and therefore requires you to manually add it to the config.
    example5: {
        options: {
            namespace: '#atomic',
            // pass a base config file
            configFile: 'test/fixtures/sample-config.js',
            // override classNames in the base config file
            config: {
                classNames: ['D(b)']
            }
            // the final config file used by the tool will be written
            // in the following file:
            configOutput: 'tmp/configOutput.json',
        },
        files: [
            {
                // parse html files to automatically create a config
                src: ['test/fixtures/*.html'],
                // generate the css in the file below
                dest: 'tmp/configBothWithParsing.css'
            }
        ]
    }
}
```

## License

This software is free to use under the Yahoo! Inc. BSD license.
See the [LICENSE file][] for license text and copyright information.

[LICENSE file]: https://github.com/acss-io/atomizer/blob/master/LICENSE.md

Third-pary open source code used are listed in our [package.json file]( https://github.com/acss-io/atomizer/blob/master/package.json).