Installation

This plugin requires Grunt 0.4. Note that ttfautohint is optional, but your generated font will not be properly hinted if it’s not installed. And make sure you don’t use ttfautohint 0.97 because that version won’t work.

stylesheets

Stylesheet type. Can be css, sass, scss or less. If sass or scss is used, _ will prefix the file (so it can be a used as a partial). You can define just stylesheet if you are generating just one type.

relativeFontPath

Type: string Default: null

Custom font path. Will be used instead of destCssin CSS file. Useful with CSS preprocessors.

version

Type: string Default: false

Version number added to .ttf version of the font (FontForge Engine only). Also used in the heading of the default demo.html template. Useful to align with the version of other assets that are part of a larger system.

htmlDemo

Type: boolean Default: true

If true, an HTML file will be available (by default, in destCSS folder) to test the render.

htmlDemoTemplate

htmlDemoFilename

Custom name for the demo HTML file (requires htmlDemo option to be true). Useful if you want to name the output something like index.html instead of the font name.

destHtml

Type: string Default: destCss value

Custom demo HTML demo path (requires htmlDemo option to be true).

embed

Type: string|array Default: false

If true embeds WOFF (only WOFF) file as data:uri.

IF ttf or woff or ttf,woff embeds TTF or/and WOFF file.

If there are more file types in types option they will be included as usual url(font.type) CSS links.

ligatures

Type: boolean Default: false

If true the generated font files and stylesheets will be generated with opentype ligature features. The character sequences to be replaced by the ligatures are determined by the file name (without extension) of the original SVG.

For example, you have a heart icon in love.svg file. The HTML <h1>I <span class="ligature-icons">love</span> you!</h1> will be rendered as I ♥ you!.

rename

Type: function Default: path.basename

You can use this function to change how file names translates to class names (the part after icon_ or icon-). By default it’s a name of a file.

For example you can group your icons into several folders and add folder name to class name:

skip

If true task will not be ran. In example, you can skip task on Windows (becase of difficult installation):

options:{

skip:require('os').platform()==='win32'

}

engine

Type: string Default: fontforge

Font rendering engine: fontforge or node. See comparison in Available Engines section above.

ie7

Type: boolean Default: false

Adds IE7 support using a *zoom: expression() hack.

optimize

Type: boolean Default: true

If false the SVGO optimization will not be used. This is useful in cases where the optimizer will produce faulty web fonts by removing relevant SVG paths or attributes.

normalize

Type: boolean Default: false

When using the fontforge engine, if false, glyphs will be generated with a fixed width equal to fontHeight. In most cases, this will produce an extra blank space for each glyph. If set to true, no extra space will be generated. Each glyph will have a width that matches its boundaries.

startCodepoint

Type: integer Default: 0xF101

Starting codepoint used for the generated glyphs. Defaults to the start of the Unicode private use area.

codepoints

Type: object Default: null

Specific codepoints to use for certain glyphs. Any glyphs not specified in the codepoints block will be given incremented as usual from the startCodepoint, skipping duplicates.

options:{

codepoints:{

single:0xE001

}

}

codepointsFile

Type: string Default: null

Uses and Saves the codepoint mapping by name to this file.

NOTE: will overwrite the set codepoints option.

autoHint

Type: boolean Default: true

Enables font auto hinting using ttfautohint.

round

Type: number Default: 10e12

Setup SVG path rounding.

fontHeight

Type: number Default: 512

The output font height.

fontFamilyName

Type: string Default: font value

If you’d like your generated fonts to have a name that’s different than the font value, you can specify this as a string. This will allow a unique display name within design authoring tools when installing fonts locally. For example, your font’s name could be GitHub Octicons with a filename of octicons.ttf.

options:{

fontFamilyName:'GitHub Octicons',

}

descent

Type: number Default: 64

The font descent. The descent should be a positive value. The ascent formula is: ascent = fontHeight - descent.

callback

Type: function Default: null

Allows for a callback to be called when the task has completed and passes in the filename of the generated font, an array of the various font types created, an array of all the glyphs created and the hash used to flush browser cache.

options:{

callback:function(filename,types,glyphs,hash){

// ...

}

}

customOutputs

Type: array Default: undefined

Allows for custom content to be generated and output in the same way as htmlDemo.

Each entry in customOutputs should be an object with the following parameters:

template - (string) the path to the underscore-template you wish to use.

dest - (string) the path to the destination where you want the resulting file to live.

context [optional] - (object) a hash of values to pass into the context of the template

At compile-time each template will have access to the same context as the compile-time environment of htmlDemoTemplate (as extended by the context object, if provided. See config-example below.

execMaxBuffer

If you get stderr maxBuffer exceeded warning message, engine probably logged a lot of warning messages. To see this warnings run grunt in verbose mode grunt --verbose. To go over this warning you can try to increase buffer size by this option. Default value is 1024 * 200

Config Examples

Simple font generation

webfont:{

icons:{

src:'icons/*.svg',

dest:'build/fonts'

}

}

Custom font name, fonts and CSS in different folders

webfont:{

icons:{

src:'icons/*.svg',

dest:'build/fonts',

destCss:'build/fonts/css',

options:{

font:'ponies'

}

}

}

Custom CSS classes

webfont:{

icons:{

src:'icons/*.svg',

dest:'build/fonts',

options:{

syntax:'bem',

templateOptions:{

baseClass:'glyph-icon',

classPrefix:'glyph_'

}

}

}

}

To use with CSS preprocessor

webfont:{

icons:{

src:'icons/*.svg',

dest:'build/fonts',

destCss:'build/styles',

options:{

stylesheet:'styl',

relativeFontPath:'/build/fonts'

}

}

}

Embedded font file

webfont:{

icons:{

src:'icons/*.svg',

dest:'build/fonts',

options:{

types:'woff',

embed:true

}

}

}

Custom Outputs

webfont:{

icons:{

src:'icons/*.svg',

dest:'build/fonts',

options:{

customOutputs:[{

template:'templates/icon-glyph-list-boilerplate.js',

dest:'build/js/icon-glyph-list.js'

},{

template:'templates/icon-glyph-config-boilerplate.json',

dest:'build/js/icon-glyphs.json'

},{

template:'templates/icon-web-home.html',

dest:'build/',

context:{

homeHeading:'Your Icon Font',

homeMessage:'The following glyphs are available in this font:'

}

}]

}

}

}

We might then include the following corresponding templates.

The first, for icon-glyph-list-boilerplate.js, a file that outputs a list of icon-glyph slugs.

// file: icon-glyph-list-boilerplate.js

(function(window) {

'use strict';

var iconList = <%= JSON.stringify(glyphs) %>;

window.iconList = iconList;

}(this));

The second, for icon-glyph-config-boilerplate.json, a file that dumps all JSON data in the current template context.

// file: icon-glyph-config-boilerplate.json

<%= JSON.stringify(arguments[0], null, '\t') %>

And finally, the third, for icon-web-home.html, a file that has access to the values provided in the context object supplied.

// file: icon-web-home.html

<!DOCTYPE html>

<html class="no-js">

<head>

<meta charset="utf-8">

<title>Context Test</title>

</head>

<body>

<h1><%= homeHeading %></h1>

<p><%= homeMessage %></p>

<ul>

<% for (var i = 0; i < glpyhs.length; i++) { %>

<li><a href="#"><%= glyphs[i] %></a></li>

<% } %>

</ul>

</body>

</html>

CSS Preprocessors Caveats

You can change CSS file syntax using stylesheet option (see above). It change file extension (so you can specify any) with some tweaks. Replace all comments with single line comments (which will be removed after compilation).

Sass

If stylesheet option is sass or scss, _ will prefix the file (so it can be a used as a partial).

Less

If stylesheet option is less, regular CSS icon classes will be expanded with corresponding Less mixins.

Using fontforge

Your paths are not overlapping. Overlapping paths will cause one of the areas to be inverted rather than combined. Use an editor to union your two paths together.

autoHint also adjusts the font file and can cause your font to look different to the SVG, so you could try switching it off (though it may make windows view of the font worse).

If you get stderr maxBuffer exceeded warning message, fontforge probably logged a lot of warning messages. To see this warnings run grunt in verbose mode grunt --verbose. To go over this warning you can try to increase buffer size by execMaxBuffer.