diff --git a/CHANGELOG.md b/CHANGELOG.md index 4c92e39..2e577ef 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,10 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [4.2.0](https://github.com/omacranger/fontawesome-subset/compare/4.1.0...4.2.0) + +- Re-add support for `woff` file formats, and allow customizing exported fonts via `targetFormats` option. + ## [4.1.0](https://github.com/omacranger/fontawesome-subset/compare/4.0.0...4.1.0) - Add support for `thin` font subset ( #23 ) diff --git a/README.md b/README.md index 6cf2a92..124d410 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,9 @@ Love FontAwesome but don't need thousands of icons bundled on every page of the site? Me either. `fontawesome-subset` is a utility for creating subsets of FontAwesome for optimized use on the web. It works by taking glyph names that you've used (`angle-left`, `caret-up`, etc) and creating an optimized font with only the glyphs you need. Yes, SVG icons and fragments are fancier and more feature filled - but if you already have a website built using the webfont - why switch -- right? ## Installation + First, install fontawesome-subset: + ```sh npm install --save-dev fontawesome-subset ``` @@ -15,44 +17,52 @@ npm install --save-dev @fortawesome/fontawesome-free ``` ## Usage + Run via your favorite task runner: + ```typescript // Import fontawesome-subset import { fontawesomeSubset } from "fontawesome-subset"; // Create or append a task to be ran with your configuration -fontawesomeSubset(['check','square','caret-up'], 'sass/webfonts'); +fontawesomeSubset(["check", "square", "caret-up"], "sass/webfonts"); ``` ### Full Options #### fontawesomeSubset(subset, output_dir, options) -- `subset` - Array containing list of glyph names (icon names) that you want to generate for the `solid` style. This can also be an object with key->value pairs for different FA styles (solid, regular¹, brands, light¹, duotone¹). Some Icons in these **¹** subsets are only available when used with FontAwesome Pro (see [below](#using-with-fontawesome-pro)). -- `output_dir` - Directory that you want the webfonts to be generated in. Relative to current NPM process. Ex: `sass/webfonts` -- `options` - Object of options to further customize the tool. - - `package` - `free` or `pro` . Defaults to `free` version. See [below](#using-with-fontawesome-pro) for Pro instructions. - - + +- `subset` - Array containing list of glyph names (icon names) that you want to generate for the `solid` style. This can also be an object with key->value pairs for different FA styles (solid, regular¹, brands, light¹, duotone¹). Some Icons in these **¹** subsets are only available when used with FontAwesome Pro (see [below](#using-with-fontawesome-pro)). +- `output_dir` - Directory that you want the webfonts to be generated in. Relative to current NPM process. Ex: `sass/webfonts` +- `options` - Object of options to further customize the tool. + - `package` - `free` or `pro` . Defaults to `free` version. See [below](#using-with-fontawesome-pro) for Pro instructions. + - `targetFormats` - A string array of one or more formats to export. Available options: `woff` `woff2` `ttf`. Defaults to `woff2` & `ttf`. + ### Using with FontAwesome Pro + FontAwesome (FA) Pro provides numerous additional icons, as well as additional font weights & styles that you can use. Obviously, you'll need to own the 'Pro' version of FA in order to use with this subsetting tool. If you've already purchased a license, follow the [installation instructions](https://fontawesome.com/docs/web/setup/packages) for getting FontAwesome Pro up and running through NPM. -After installation, you can supply additional information to the `subset` parameter of `fontawesomeSubset` to create families for specific font styles. Make sure to include `package: 'pro'` inside the options parameter to generate from the Pro source instead and enable font creation for different weights / styles. +After installation, you can supply additional information to the `subset` parameter of `fontawesomeSubset` to create families for specific font styles. Make sure to include `package: 'pro'` inside the options parameter to generate from the Pro source instead and enable font creation for different weights / styles. #### Example generating separate glyphs for 'regular' and 'solid' styles: + ```javascript -fontawesomeSubset({ - regular: ['check','square','caret-up'], - solid: ['plus','minus'] -}, -'sass/webfonts', -{ - package: 'pro' -}); +fontawesomeSubset( + { + regular: ["check", "square", "caret-up"], + solid: ["plus", "minus"], + }, + "sass/webfonts", + { + package: "pro", + } +); ``` You can use any of the weights / sets provided by FontAwesome Pro including `solid`, `regular`, `light`, `brands`, or `duotone`. You can mix and match and provide as many glyphs as you plan on using to trim it down. The above example would output a directory with the following structure: + ``` /sass/ /webfonts/ @@ -68,22 +78,22 @@ It is still up to you to determine which glyphs you need and to pass them to the If you already have FA installed on your server in relation to your NPM project, you can point the `output_dir` to the webfonts directory that you're already loading and the script will overwrite the current fonts with the newly minified / optimized versions. If you plan on getting a bit more granular you can always edit the `_icons.scss` file provided by the FA team and remove all glyphs that you're not using to save a few more KBs for your end user. -Here's an example of the `_icons.scss` file on a project I've worked on using a sass map for the glyph name `->` variable provided in the `_variables.scss` file: +Here's an example of the `_icons.scss` file on a project I've worked on using a sass map for the glyph name `->` variable provided in the `_variables.scss` file: ```scss $icons: ( - shopping-cart: $fa-var-shopping-cart, - chevron-right: $fa-var-chevron-right, - chevron-left: $fa-var-chevron-left, - chevron-down: $fa-var-chevron-down, - check-square: $fa-var-check-square, - square: $fa-var-square, - caret-up: $fa-var-caret-up, - plus: $fa-var-plus, - minus: $fa-var-minus, - times: $fa-var-times, - search: $fa-var-search, - check: $fa-var-check, + shopping-cart: $fa-var-shopping-cart, + chevron-right: $fa-var-chevron-right, + chevron-left: $fa-var-chevron-left, + chevron-down: $fa-var-chevron-down, + check-square: $fa-var-check-square, + square: $fa-var-square, + caret-up: $fa-var-caret-up, + plus: $fa-var-plus, + minus: $fa-var-minus, + times: $fa-var-times, + search: $fa-var-search, + check: $fa-var-check, ); @each $key, $value in $icons { diff --git a/package.json b/package.json index 007293a..a4a4fc7 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "fontawesome-subset", - "version": "4.1.0", + "version": "4.2.0", "description": "Utility to create subsets for FontAwesome and FontAwesome Pro.", "main": "dist/index.js", "types": "dist/index.d.ts",