grunt-favicons
Version:
Generate favicon.ico and icons for iOS, Android, Windows and Firefox (OS)
352 lines (248 loc) • 10 kB
Markdown
# grunt-favicons
[](https://travis-ci.org/gleero/grunt-favicons) [](http://badge.fury.io/js/grunt-favicons)
Generates all known types and sizes icons from PNG image. Uses ImageMagick.
***Input***: square logo in png. You can also keep near the source files with resolution prefix e.g. `source.16x16.png`.
***Output***:
- `favicon.ico` (16x16, 32x32, 48x48) — desktop browsers, address bar, tabs, safari reading list, non-retina iPhone, windows 7+ taskbar, windows desktop;
- `favicon.png` (64x64) — modern browsers;
- `apple-touch-icon.png` (57x57) — iPhone non-retina, Android 2.1+;
- `apple-touch-icon-60x60.png` (60x60) — iPhone iOS7+;
- `apple-touch-icon-72x72.png` (72x72) — iPad non-retina;
- `apple-touch-icon-76x76.png` (76x76) — iPad non-retina iOS 7;
- `apple-touch-icon-114x114.png` (114x114) — iPhone retina, iOS 6 and lower;
- `apple-touch-icon-120x120.png` (120x120) — iPhone retina, iOS 7 and higher;
- `apple-touch-icon-144x144.png` (144x144) — iPad retina;
- `apple-touch-icon-152x152.png` (152x152) — iPad retina iOS 7;
- `windows-tile-144x144.png` (144x144) — Windows 8 tile;
- `coast-icon-228x228.png` (228x228) - Coast browser;
- `firefox-icon-16x16.png` (16x16) - Firefox on Android / Windows;
- `firefox-icon-30x30.png` (30x30) - Firefox OS;
- `firefox-icon-32x32.png` (32x32) - Firefox on Android / Windows;
- `firefox-icon-48x48.png` (48x48) - Firefox on Android / Windows;
- `firefox-icon-60x60.png` (60x60) - Firefox OS;
- `firefox-icon-64x64.png` (64x64) - Firefox on Android / Windows;
- `firefox-icon-90x90.png` (90x90) - Firefox OS;
- `firefox-icon-120x120.png` (120x120) - Firefox OS;
- `firefox-icon-128x128.png` (128x128) - Firefox on Android / Windows;
- `firefox-icon-256x256.png` (256x256) - Firefox on Android / Windows;
- `homescreen-192x192.png` (192x192) - Android Homescreen.
Adds changes to `html` file.
## Getting Started
This plugin requires Grunt `~0.4.1` and ImageMagick.
Installing ImageMagick:
_on Mac:_
```shell
brew install imagemagick
```
_on Linux:_
```shell
apt-get install imagemagick
```
_On Windows:_
```shell
cinst imagemagick.app
```
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-favicons --save-dev
```
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
```js
grunt.loadNpmTasks('grunt-favicons');
```
## The "favicons" task
### Overview
In your project's Gruntfile, add a section named `favicons` to the data object passed into `grunt.initConfig()`.
```js
grunt.initConfig({
favicons: {
options: {
// Task-specific options go here.
},
your_target: {
// Target-specific file lists and/or options go here.
},
},
})
```
### Options
#### options.html
Type: `String`
Default value: `''`
Path to HTML you want to add links to icons.
#### options.truncateHTML
Type: `Boolean`
Default value: `false`
Truncate the HTML file before adding links.
#### options.HTMLPrefix
Type: `String`
Default value: `''`
The path to the folder that contains the icons.
#### options.apple
Type: `Boolean`
Default value: `true`
Generate apple icons.
#### options.regular
Type: `Boolean`
Default value: `true`
Generate regular icons.
#### options.trueColor
Type: `Boolean`
Default value: `false`
Use true color favicon.ico or 256 сolor. True color are larger.
#### options.sharp
Type: `Float`
Default value: `0`
Adaptively sharpen pixels. Increase effect near edges. 0 — disable.
#### options.precomposed
Type: `Boolean`
Default value: `true`
When is false Safari on iOS < 7 add any effects to the icon.
#### options.appleTouchBackgroundColor
Type: `String`
Default value: `auto`
Values: `auto|none|#COLOR`
iOS icon can't be transparent. It needs background. If option set to `auto` color is selected automatically. `none` leaves transparency.
#### options.appleTouchPadding
Type: `Integer`
Default value: `15`
Padding in iOS icons. In percents.
#### options.windowsTile
Type: `Boolean`
Default value: `true`
Add Windows 8 tile icon.
#### options.coast
Type: `Boolean`
Default value: `false`
Add 228x228 icon for [Coast browser](http://coastbyopera.com/).
#### options.tileBlackWhite
Type: `Boolean`
Default value: `true`
Make white-only icon on Windows 8 tile.
#### options.tileColor
Type: `String`
Default value: `auto`
Values: `auto|none|#COLOR`
Background color for Windows 8 tile. If option set to `auto` color is selected automatically. `none` leaves transparency.
#### options.firefox
Type: `Boolean`
Default value: `false`
Add icons for [Firefox OS](http://www.mozilla.org/de/firefox/os/) and Firefox on Android and Windows.
#### options.firefoxManifest
Type: `String`
Default value: `''`
Path to [Firefox manifest](https://developer.mozilla.org/en-US/Apps/Developing/Manifest) you want to add links to icons.
#### options.firefoxRound
Type: `Boolean`
Default value: `false`
Make Firefox OS icons rounded.
#### options.androidHomescreen
Type: `Boolean`
Default value: `false`
Make [Android Homescreen](https://developer.chrome.com/multidevice/android/installtohomescreen) app icon.
#### options.indent
Type: `String`
Default value: `\t`
String value for the indentation to be used for each link in the resulting HTML. Defaults to a tab character.
### Low resolution
If you reduce the image to 16x16, it will blured. To avoid this, you can put near source image the prefixes. For example: source image called `logo.png`. If you put nearly `logo.16x16.png` then it will be used.
#### options.getLowResolutionImagePath
Type: `Function`
Default value:
```js
getLowResolutionImagePath: function (srcFilePath, size) {
var extname = path.extname(srcFilePath);
return path.join(path.dirname(srcFilePath), path.basename(srcFilePath, extname) + '.' + size + extname);
}
```
Change low resolution image path (default template of naming).
### Usage Examples
#### Default Options
In this example, the default options are used to create `favicon.ico`, `favicon.png`, apple touch icons and windows 8 tile.
```js
grunt.initConfig({
favicons: {
options: {},
icons: {
src: 'src/logo.png',
dest: 'build/images'
}
},
})
```
#### Custom Options
```js
grunt.initConfig({
favicons: {
options: {
trueColor: true,
precomposed: true,
appleTouchBackgroundColor: "#e2b2c2",
coast: true,
windowsTile: true,
tileBlackWhite: false,
tileColor: "auto",
html: 'build/out/index.html',
HTMLPrefix: "/images/icons/"
},
icons: {
src: 'src/logo.png',
dest: 'build/images/icons'
}
},
})
```
## 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](http://gruntjs.com/).
## Feedback
Author: Vladimir Perekladov
Website: [gleero.com](http://gleero.com/)
E-mail: [gleero@gmail.com](mailto:gleero@gmail.com)
Big thanks for contributing:
- [ro-ka](https://github.com/ro-ka)
- [kfiku](https://github.com/kfiku)
- [debugwand](https://github.com/debugwand)
- [gausie](https://github.com/gausie)
- [alaz](https://github.com/alaz)
## Release History
### 2014-04-18 v0.6.4
* [#28](https://github.com/gleero/grunt-favicons/issues/28) Add Android Homescreen app icon.
### 2014-04-01 v0.6.3
* [#21](https://github.com/gleero/grunt-favicons/issues/21) Add `sharp` option for sharping icons.
### 2014-04-01 v0.6.2
* [#24](https://github.com/gleero/grunt-favicons/issues/24) Apple and regular favicons are now optional.
### 2014-03-05 v0.6.1
* Improved HTML tags clearing.
### 2013-12-19 v0.6.0
* [#14](https://github.com/gleero/grunt-favicons/pull/14) Add Firefox icon 120x120;
* [#17](https://github.com/gleero/grunt-favicons/issues/17) Append 70x70, 150x150 and 310x310 for MS tiles;
* Append Apple touch icon 60x60 for iOS 7;
* HTML link sizes order;
* All Apple touch icons contain;
* Linebreaks in HTML;
* [#16](https://github.com/gleero/grunt-favicons/issues/16), [#15](https://github.com/gleero/grunt-favicons/issues/15).
### 2013-12-11 v0.5.1
* Small bugfix ([#12](https://github.com/gleero/grunt-favicons/pull/12), [#13](https://github.com/gleero/grunt-favicons/pull/13)).
### 2013-11-30 v0.5.0
* Add iOS icons padding;
* Support rounded Firefox OS icons.
### 2013-11-26 v0.4.0
* Small bugfix;
* [#4](https://github.com/gleero/grunt-favicons/pull/4) Supports php-tags in `HTMLPrefix`;
* [#5](https://github.com/gleero/grunt-favicons/pull/5) The task on startup removes all possible icons tags from `html`;
* [#8](https://github.com/gleero/grunt-favicons/pull/8) Firefox OS and Firefox for Android and Windows.
### 2013-10-11 v0.3.2
* [#3](https://github.com/gleero/grunt-favicons/pull/3) If destination folder does not exist, create it and continue.
### 2013-10-02 v0.3.0
* Add 76x76 for iPad non-retina iOS 7;
* Add 152x152 for iPad retina iOS 7;
* Disable `non-precomposed` icons for iOS 7 (is no longer supported).
### 2013-09-09 v0.2.0
* Add source image prefix;
* 228х228 Coast browser support;
* Readme.md fix.
[](http://githalytics.com/gleero/grunt-favicons)