# grunt-fontello

> donwload font icons from fontello.com

## Getting Started
This plugin requires Grunt `~0.4.1`

If you haven't used [Grunt](http://gruntjs.com/) before, be sure to check out the [Getting Started](http://gruntjs.com/getting-started) guide, as it explains how to create a [Gruntfile](http://gruntjs.com/sample-gruntfile) as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

```shell
npm install grunt-fontello --save-dev
```

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

```js
grunt.loadNpmTasks('grunt-fontello');
```

## The "fontello" task

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

```js
grunt.initConfig({
  fontello: {
    dist: {
      options: {
        config       : 'config.json',
        fonts        : 'output/fonts',
        styles       : 'output/css',
        preprocessor : 'scss',
        force        : true
      }
    }
  }
})
```

### Options

#### options.config
Type: `String`
Default value: `"config.json"`

Path to your config.json file. Generate custom font icons [here](http://www.fontello.com).

#### options.zip
Type: `String`
Default value: `"."`

Folder to extract the full archive.

#### options.fonts
Type: `String`
Default value: `"fonts"`

Path to extract font files (`*.eot`, `*.woff`, `*.svg`, `*.ttf`).

#### options.styles
Type: `String`
Default value: `"css"`

Path to extract the stylesheets to.

#### options.preprocessor
Type: `String`
Default value: `none`

By default the outputted stylesheet will be _.css_. Changing this to `less` or `scss` will
change the output to _.less_ or _.scss_ respectively.

#### options.force
Type: `Boolean`
Default value: `false`

By default, if the folder specified in _options.fonts_, _options.zip_ and _options.styles_ do not exist, the task will throw an error. Setting this option to `true` will create the directory structure specified.

#### options.exclude
Type: `Array`
Default value: `[]`

An array of names of files which should be excluded. Accepts strings and regular expressions.

#### options.cssFontPath
Type: `String`
Default value: `undefined`

An explicit path to where the fonts are relative to the _.css_/_.scss_ file.

#### options.prefix
Type: `String`
Default value: `fontello`

A string representing the prefix of the stylesheets generated by fontello.

### Example

#### Multiple Targets
```js
grunt.initConfig({
  fontello: {
    options: {
      preprocessor : 'scss',
      force        : true
    },
    dist: {
      options: {
          fonts   : 'output/fonts',
          styles  : 'output/css',
      }
    },
    dev: {
      options: {
          config  : 'test/config.json',
          fonts   : 'test/output/fonts',
          styles  : 'test/output/css',
      }
    }
  }
})

grunt.loadNpmTasks('grunt-fontello');
grunt.registerTask('default', ['fontello:dist']);
```

#### Exclude files
```js
grunt.initConfig({
  fontello: {
    dist: {
      options: {
        fonts   : 'output/fonts',
        styles  : 'output/css',
        exclude : ['animation.css', 'fontello-ie7-codes.css', 'fontello.eot'],
      }
    }
  }
})
```