1 |
|
2 | # This file is automatically generated by a `metapak`
|
3 | # module. Do not change it elsewhere, changes would
|
4 | # be overridden.
|
5 | -->
|
6 |
|
7 | # svgicons2svgfont
|
8 |
|
9 | > Read a set of SVG icons and ouput a SVG font
|
10 |
|
11 | [![NPM version](https://badge.fury.io/js/svgicons2svgfont.svg)](https://npmjs.org/package/svgicons2svgfont)
|
12 | [![Run tests](https://github.com/nfroidure/svgicons2svgfont/actions/workflows/test.yml/badge.svg)](https://github.com/nfroidure/svgicons2svgfont/actions/workflows/test.yml)
|
13 | [![Dependency Status](https://david-dm.org/nfroidure/svgicons2svgfont.svg)](https://david-dm.org/nfroidure/svgicons2svgfont)
|
14 | [![devDependency Status](https://david-dm.org/nfroidure/svgicons2svgfont/dev-status.svg)](https://david-dm.org/nfroidure/svgicons2svgfont#info=devDependencies)
|
15 | [![Coverage Status](https://coveralls.io/repos/nfroidure/svgicons2svgfont/badge.svg?branch=master)](https://coveralls.io/r/nfroidure/svgicons2svgfont?branch=master)
|
16 | [![Code Climate](https://codeclimate.com/github/nfroidure/svgicons2svgfont.svg)](https://codeclimate.com/github/nfroidure/svgicons2svgfont)
|
17 | [![Dependency Status](https://dependencyci.com/github/nfroidure/svgicons2svgfont/badge)](https://dependencyci.com/github/nfroidure/svgicons2svgfont)
|
18 |
|
19 | svgicons2svgfont is a simple tool to merge
|
20 | multiple icons to an SVG font.
|
21 |
|
22 | 'rect', 'line', 'circle', 'ellipsis', 'polyline' and 'polygon' shapes will be
|
23 | converted to pathes. Multiple pathes will be merged.
|
24 |
|
25 | Transform attributes support is currenly experimental,
|
26 | [report issues if any](https://github.com/nfroidure/svgicons2svgfont/issues/6).
|
27 |
|
28 | You can test this library with the
|
29 | [frontend generator](http://nfroidure.github.io/svgiconfont/).
|
30 |
|
31 | You may want to convert fonts to icons, if so use
|
32 | [svgfont2svgicons](https://github.com/nfroidure/svgfont2svgicons).
|
33 |
|
34 | ## Usage
|
35 |
|
36 | ### In your scripts
|
37 |
|
38 | ```js
|
39 | const SVGIcons2SVGFontStream = require('svgicons2svgfont');
|
40 | const fs = require('fs');
|
41 | const fontStream = new SVGIcons2SVGFontStream({
|
42 | fontName: 'hello',
|
43 | });
|
44 |
|
45 | // Setting the font destination
|
46 | fontStream
|
47 | .pipe(fs.createWriteStream('fonts/hello.svg'))
|
48 | .on('finish', function () {
|
49 | console.log('Font successfully created!');
|
50 | })
|
51 | .on('error', function (err) {
|
52 | console.log(err);
|
53 | });
|
54 |
|
55 | // Writing glyphs
|
56 | const glyph1 = fs.createReadStream('icons/icon1.svg');
|
57 | glyph1.metadata = {
|
58 | unicode: ['\uE001\uE002'],
|
59 | name: 'icon1',
|
60 | };
|
61 | fontStream.write(glyph1);
|
62 |
|
63 | // Multiple unicode values are possible
|
64 | const glyph2 = fs.createReadStream('icons/icon1.svg');
|
65 | glyph2.metadata = {
|
66 | unicode: ['\uE002', '\uEA02'],
|
67 | name: 'icon2',
|
68 | };
|
69 | fontStream.write(glyph2);
|
70 |
|
71 | // Either ligatures are available
|
72 | const glyph3 = fs.createReadStream('icons/icon1.svg');
|
73 | glyph3.metadata = {
|
74 | unicode: ['\uE001\uE002'],
|
75 | name: 'icon1-icon2',
|
76 | };
|
77 | fontStream.write(glyph3);
|
78 |
|
79 | // Do not forget to end the stream
|
80 | fontStream.end();
|
81 | ```
|
82 |
|
83 | ## CLI interface
|
84 |
|
85 | All options are available except the `log` one by using this pattern:
|
86 | `--{LOWER_CASE(optionName)}={optionValue}`.
|
87 |
|
88 | ```sh
|
89 | svgicons2svgfont --fontname=hello -o font/destination/file.svg icons/directory/*.svg
|
90 | ```
|
91 |
|
92 | Note that you won't be able to customize icon names or icons unicodes by
|
93 | passing options but by using the following convention to name your icons files:
|
94 | `${icon.unicode}-${icon.name}.svg` where `icon.unicode` is a comma separated
|
95 | list of unicode strings (ex: 'uEA01,uE001,uE001uE002', note that the last
|
96 | string is in fact a ligature).
|
97 |
|
98 | There is a few more options for the CLI interface, you can list all of them:
|
99 |
|
100 | ```txt
|
101 | svgicons2svgfont --help
|
102 | # Usage: svgicons2svgfont [options] <icons ...>
|
103 | #
|
104 | # Options:
|
105 | #
|
106 | # -V, --version output the version number
|
107 | # -v, --verbose tell me everything!
|
108 | # -o, --output [/dev/stdout] file to write output to
|
109 | # -f, --fontname [value] the font family name you want [iconfont]
|
110 | # -i, --fontId [value] the font id you want [fontname]
|
111 | # -st, --style [value] the font style you want
|
112 | # -we, --weight [value] the font weight you want
|
113 | # -w, --fixedWidth creates a monospace font of the width of the largest input icon
|
114 | # -c, --centerhorizontally calculate the bounds of a glyph and center it horizontally
|
115 | # -y, --centervertically centers the glyphs vertically in the generated font.
|
116 | # -n, --normalize normalize icons by scaling them to the height of the highest icon
|
117 | # -h, --height [value] the output font height [MAX(icons.height)] (icons will be scaled so the highest has this height)
|
118 | # -r, --round [value] setup the SVG path rounding [10e12]
|
119 | # -d, --descent [value] the font descent [0]
|
120 | # -a, --ascent [value] the font ascent [height - descent]
|
121 | # -s, --startunicode [value] the start unicode codepoint for unprefixed files [0xEA01]
|
122 | # -a, --prependUnicode prefix files with their automatically allocated unicode code point
|
123 | # -m, --metadata content of the metadata tag
|
124 | # -h, --help output usage information
|
125 | ```
|
126 |
|
127 | ## API
|
128 |
|
129 | ### new SVGIcons2SVGFontStream(options)
|
130 |
|
131 | #### options.fontName
|
132 |
|
133 | Type: `String`
|
134 | Default value: `'iconfont'`
|
135 |
|
136 | The font family name you want.
|
137 |
|
138 | #### options.fontId
|
139 |
|
140 | Type: `String`
|
141 | Default value: the options.fontName value
|
142 |
|
143 | The font id you want.
|
144 |
|
145 | #### options.fontStyle
|
146 |
|
147 | Type: `String`
|
148 | Default value: `''`
|
149 |
|
150 | The font style you want.
|
151 |
|
152 | #### options.fontWeight
|
153 |
|
154 | Type: `String`
|
155 | Default value: `''`
|
156 |
|
157 | The font weight you want.
|
158 |
|
159 | #### options.fixedWidth
|
160 |
|
161 | Type: `Boolean`
|
162 | Default value: `false`
|
163 |
|
164 | Creates a monospace font of the width of the largest input icon.
|
165 |
|
166 | #### options.centerHorizontally
|
167 |
|
168 | Type: `Boolean`
|
169 | Default value: `false`
|
170 |
|
171 | Calculate the bounds of a glyph and center it horizontally.
|
172 |
|
173 | #### options.centerVertically
|
174 |
|
175 | Type: `Boolean`
|
176 | Default value: `false`
|
177 |
|
178 | Centers the glyphs vertically in the generated font.
|
179 |
|
180 | #### options.normalize
|
181 |
|
182 | Type: `Boolean`
|
183 | Default value: `false`
|
184 |
|
185 | Normalize icons by scaling them to the height of the highest icon.
|
186 |
|
187 | #### options.fontHeight
|
188 |
|
189 | Type: `Number`
|
190 | Default value: `MAX(icons.height)`
|
191 | The outputted font height (defaults to the height of the highest input icon).
|
192 |
|
193 | #### options.round
|
194 |
|
195 | Type: `Number`
|
196 | Default value: `10e12`
|
197 | Setup SVG path rounding.
|
198 |
|
199 | #### options.descent
|
200 |
|
201 | Type: `Number`
|
202 | Default value: `0`
|
203 |
|
204 | The font descent. It is usefull to fix the font baseline yourself.
|
205 |
|
206 | **Warning:** The descent is a positive value!
|
207 |
|
208 | #### options.ascent
|
209 |
|
210 | Type: `Number`
|
211 | Default value: `fontHeight - descent`
|
212 |
|
213 | The font ascent. Use this options only if you know what you're doing. A suitable
|
214 | value for this is computed for you.
|
215 |
|
216 | #### options.metadata
|
217 |
|
218 | Type: `String`
|
219 | Default value: `undefined`
|
220 |
|
221 | The font [metadata](http://www.w3.org/TR/SVG/metadata.html). You can set any
|
222 | character data in but it is the be suited place for a copyright mention.
|
223 |
|
224 | #### options.metadataProvider
|
225 |
|
226 | Type: `(file: string, cb: (err: any, metadata: {file: string, name: string, unicode: string[], renamed: boolean}) => void`
|
227 |
|
228 | Default value: `require('svgicons2svgfont/src/metadata')(options)`
|
229 |
|
230 | A function which determines the metadata for an icon. It takes a parameter `file` with an icon svg and should return
|
231 | icon metadata (asynchronously) via the callback function. You can use this function to provide custom logic for svg to
|
232 | codepoint mapping.
|
233 |
|
234 | | | |
|
235 | | ------------------ | ---------------------------------------------------------------------------------------- |
|
236 | | `metadata.path` | The path to the icon file. (The original `file` param is the file was not moved.) |
|
237 | | `metadata.name` | The name of the icon |
|
238 | | `metadata.unicode` | The unicode codepoints corresponding to this glyph. Each should be a 1-codepoint string. |
|
239 | | `metadata.renamed` | Wether the original file was moved (e.g. to prefix it with its unicode codepoint) |
|
240 |
|
241 | #### options.log
|
242 |
|
243 | Type: `Function`
|
244 | Default value: `console.log`
|
245 |
|
246 | Allows you to provide your own logging function. Set to `function(){}` to
|
247 | disable logging.
|
248 |
|
249 | ## Build systems
|
250 |
|
251 | ### Grunt plugins
|
252 |
|
253 | [grunt-svgicons2svgfont](https://github.com/nfroidure/grunt-svgicons2svgfont)
|
254 | and [grunt-webfont](https://github.com/sapegin/grunt-webfont).
|
255 |
|
256 | ### Gulp plugins
|
257 |
|
258 | Try [gulp-iconfont](https://github.com/nfroidure/gulp-iconfont) and
|
259 | [gulp-svgicons2svgfont](https://github.com/nfroidure/gulp-svgicons2svgfont).
|
260 |
|
261 | ### Stylus plugin
|
262 |
|
263 | Use [stylus-iconfont](https://www.npmjs.org/package/stylus-iconfont).
|
264 |
|
265 | ### Mimosa plugin
|
266 |
|
267 | Use [mimosa-svgs-to-iconfonts](https://www.npmjs.org/package/mimosa-svgs-to-iconfonts).
|
268 |
|
269 | ## CLI alternatives
|
270 |
|
271 | You can combine this plugin's CLI interface with
|
272 | [svg2ttf](https://www.npmjs.com/package/svg2ttf),
|
273 | [ttf2eot](https://www.npmjs.com/package/ttf2eot),
|
274 | [ttf2woff](https://www.npmjs.com/package/ttf2woff)
|
275 | and [ttf2woff2](https://www.npmjs.com/package/ttf2woff2).
|
276 | You can also use [webfonts-generator](https://www.npmjs.com/package/webfonts-generator).
|
277 |
|
278 | ## Stats
|
279 |
|
280 | [![NPM](https://nodei.co/npm/svgicons2svgfont.png?downloads=true&stars=true)](https://nodei.co/npm/svgicons2svgfont/)
|
281 | [![NPM](https://nodei.co/npm-dl/svgicons2svgfont.png)](https://nodei.co/npm/svgicons2svgfont/)
|
282 |
|
283 | ## Contributing
|
284 |
|
285 | Feel free to push your code if you agree with publishing under the MIT license.
|
286 |
|
287 | # License
|
288 |
|
289 | [MIT](https://github.com/nfroidure/svgicons2svgfont/blob/master/LICENSE)
|