webfont 12.3.0 → 12.4.1

package/NOTICE.md

@@ -1,4 +1,4 @@
-# webfont — Legal notice
+# webfont — Legal Notices
 
 This document covers **copyright and licensing for fonts you process**, **disclaimers** about using the webfont software, **community attribution guidelines**, and **third-party open-source components** bundled with or used by this project.
 

package/README.md

@@ -16,7 +16,7 @@ See **[FEATURES.md](./FEATURES.md)** for the canonical capability list (what is
 ## Features
 
 - **SVG icon pipeline** (default): `.svg` icons → `svg`, `ttf`, `eot`, `woff`, `woff2` (not `otf`);
-- **TTF encoding**: one or more `.ttf` files → `ttf` (pass-through), `eot`, `woff`, and/or `woff2` (auto-detected — no extra flag);
+- **TTF encoding**: one or more `.ttf` files → `ttf` (pass-through), `svg` (SVG font), `eot`, `woff`, and/or `woff2` (auto-detected — no extra flag);
 - **Webfont decompression**: one `.woff` or `.woff2` file → `ttf` and/or `otf` matching the **embedded SFNT flavor** (decompress only — not TTF ↔ OTF transcoding);
 - Config files: `JavaScript`, `JSON`, or `YAML` via [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig);
 - Built-in and custom CSS templates (`css`, `scss`, [`styl`](https://github.com/itgalaxy/webfont/pull/164/));
@@ -30,7 +30,7 @@ webfont runs one of three pipelines depending on matched input files. They canno
 | Mode | Input | Outputs | Notes |
 |------|--------|---------|--------|
 | **SVG icons** | One or more `.svg` files | `svg`, `ttf`, `eot`, `woff`, `woff2` | Default. Builds TrueType via `svg2ttf`. **`otf` is rejected** — use `ttf`. |
-| **TTF encoding** | One or more `.ttf` files | `ttf`, `eot`, `woff`, and/or `woff2` per input | Auto-detected. Default when SVG-pipeline `formats` are still configured: `woff` + `woff2`. No templates. |
+| **TTF encoding** | One or more `.ttf` files | `ttf`, `svg` (SVG font), `eot`, `woff`, and/or `woff2` per input | Auto-detected. Default when SVG-pipeline `formats` are still configured: `woff` + `woff2` (`svg` is opt-in). No templates. |
 | **Webfont decompress** | One or more `.woff` / `.woff2` paths, globs, or `http(s)` URLs | `ttf` and/or `otf` per input | One output file per source (basename from filename; collisions get `-woff`/`-woff2`). Not a single merged font. |
 
 **Not supported today**
@@ -49,12 +49,71 @@ webfont is a technical tool. **Decompressing or generating fonts does not grant
 
 Full details, disclaimers, community attribution guidelines, and third-party library notices: **[NOTICE.md](./NOTICE.md)**.
 
+## Comparison with `webfonts`
+
+`webfont` (this project) is sometimes confused with the older, **unmaintained** [`webfonts`](https://github.com/uipoet/webfonts) package (note the trailing `s`). `webfonts` last shipped around 2015 and requires a **Java** runtime (it bundles `batik-ttf2svg`, `sfnt2woff`, and `ttf2eot`). `webfont` is **pure JavaScript**, actively maintained, and does everything the *useful* parts of `webfonts` did — plus SVG-icon fonts, WOFF2, decompression, templates, and a Node.js API.
+
+| Capability | `webfont` (this project) | `webfonts` ([uipoet/webfonts](https://github.com/uipoet/webfonts)) |
+|------------|:------------------------:|:-----------------------------------------------------------------:|
+| Maintained | ✅ | ❌ (last release ~2015) |
+| Runtime | Pure JS (Node.js) | Node.js **+ Java** |
+| SVG icons → font | ✅ (default pipeline) | ❌ |
+| TTF input → web formats | ✅ | ✅ |
+| Output: `woff2` (Brotli) | ✅ | ❌ |
+| Output: `woff` / `eot` | ✅ | ✅ |
+| Output: `svg` font | ✅ (`-f svg`, opt-in) | ✅ |
+| Choose which formats to emit | ✅ (`-f` / `formats`) | ❌ (always `woff` + `eot` + `svg`) |
+| WOFF/WOFF2 → TTF/OTF decompression | ✅ | ❌ |
+| Node.js / programmatic API | ✅ (`webfont()`) | ❌ (CLI only) |
+| CSS / SCSS / Styl templates | ✅ | ❌ (manual `@font-face` snippet) |
+| Config files (cosmiconfig) | ✅ | ❌ |
+| `.otf` as a **source** | ❌ ([tracking #767](https://github.com/itgalaxy/webfont/issues/767)) | ❌ ([requested](https://github.com/uipoet/webfonts/issues/4)) |
+
+### Migrating from `webfonts`
+
+```bash
+# webfonts (unmaintained): converts a directory of TTFs, always emits woff + eot + svg
+webfonts fonts/ -o dist/
+
+# webfont: pick your formats explicitly (woff2 recommended for the web)
+webfont "fonts/*.ttf" -f woff2,woff,eot,svg -d dist --dest-create
+```
+
+`webfont` adds `woff2` (much smaller than the legacy formats), lets you emit only what you ship, and needs no Java toolchain.
+
+## Comparison with `grunt-webfont`
+
+[`grunt-webfont`](https://github.com/sapegin/grunt-webfont) is the classic "SVG → webfont" **Grunt plugin** (~1.1k★, MIT). It is **archived** (read-only since 2021, last release `v1.2.0`), and its best-fidelity output relies on a native **FontForge** binary (its pure-`node` engine can't do ligatures). `webfont` is a framework-agnostic, actively maintained, pure-JS library **and** CLI: it does everything grunt-webfont *generated* — plus TTF encoding, WOFF/WOFF2 decompression, more templates, and programmatic hooks. The one thing grunt-webfont has that `webfont` doesn't is native Grunt wiring (tracked in [#771](https://github.com/itgalaxy/webfont/issues/771)); you can already drive `webfont()` from a small custom Grunt task.
+
+| Capability | `webfont` (this project) | `grunt-webfont` ([sapegin/grunt-webfont](https://github.com/sapegin/grunt-webfont)) |
+|------------|:------------------------:|:----------------------------------------------------------------------------------:|
+| Maintained | ✅ | ❌ (archived 2021, `v1.2.0`) |
+| Runtime | Node API **+ CLI** (any build tool) | **Grunt task only** |
+| Engine | Pure JS (`svg2ttf`) | `node` **or** FontForge binary |
+| SVG icons → font | ✅ | ✅ |
+| Output formats | `svg, ttf, eot, woff, woff2` | `eot, woff2, woff, ttf, svg` |
+| TTF input → web formats | ✅ | ❌ |
+| WOFF/WOFF2 → TTF/OTF decompression | ✅ | ❌ |
+| Stylesheets | `css, scss, styl, html, json` + custom Nunjucks, multiple per run | `css, sass, scss, less, stylus` + custom |
+| CSS syntax presets (BEM / Bootstrap) | ❌ (use a custom template) | ✅ |
+| `data:uri` embedding in CSS | ❌ | ✅ (`embed`) |
+| Autohinting (`ttfautohint`) | via `ttfPostProcess` hook (external, opt-in) | built-in (`autoHint`) |
+| Ligatures | ✅ (opt-in) | ✅ (FontForge engine only) |
+| Codepoint map persistence | ❌ | ✅ (`codepointsFile`) |
+| Programmatic API | ✅ (`webfont()`) | ❌ (Grunt only) |
+| SVG diagnostics | ✅ (alpha) | ❌ |
+| Grunt integration | ⏳ ([#771](https://github.com/itgalaxy/webfont/issues/771)) | ✅ (native) |
+
+If you only need the generation that grunt-webfont did, `webfont` is a maintained, FontForge-free replacement. If you specifically need BEM/Bootstrap CSS presets or `data:uri` embedding today, use a [custom template](#template).
+
 ## Table Of Contents
 
 - [Webfont](#webfont)
   - [Features](#features)
   - [Input modes](#input-modes)
   - [Font licensing](#font-licensing)
+  - [Comparison with `webfonts`](#comparison-with-webfonts)
+  - [Comparison with `grunt-webfont`](#comparison-with-grunt-webfont)
   - [Installation](#installation)
   - [Usage](#usage)
   - [Options](#options)
@@ -68,7 +127,7 @@ Full details, disclaimers, community attribution guidelines, and third-party lib
 - [Roadmap](#roadmap)
 - [Contribution](#contribution)
 - [Changelog](#changelog)
-- [Legal notice](#legal-notice)
+- [Legal Notices](#legal-notices)
 - [License](#license)
 
 ---
@@ -157,6 +216,13 @@ const subset = await webfont({
   formats: ["woff2"],
 });
 
+// TTF → SVG font (legacy format; opt-in, pure JS via fonteditor-core)
+const svgFont = await webfont({
+  files: "path/to/font.ttf",
+  formats: ["svg"],
+});
+// svgFont.svg → SVG font as a string
+
 // Batch: multiple TTF files in one run
 const batch = await webfont({
   files: ["fonts/Inter-Regular.ttf", "fonts/Inter-Bold.ttf"],
@@ -292,7 +358,7 @@ Notes:
 - Possible values: `svg`, `ttf`, `otf`, `eot`, `woff`, `woff2`
 - Description: Font file types to generate.
   - **SVG input**: `svg`, `ttf`, `eot`, `woff`, `woff2` only. **`otf` is not supported** (pipeline uses TrueType outlines).
-  - **TTF input**: `ttf`, `eot`, `woff`, and/or `woff2` only. **`svg` and `otf` are not produced** in this mode.
+  - **TTF input**: `svg` (SVG font), `ttf`, `eot`, `woff`, and/or `woff2`. `svg` is **opt-in** (not in the default `woff` + `woff2` set); **`otf` is not produced** in this mode.
   - **WOFF/WOFF2 input**: `ttf` and/or `otf` only — must match the decompressed SFNT flavor inside the file (not arbitrary transcoding). `eot`, `woff`, `woff2`, and `svg` are not produced in this mode.
 - CLI: pass `-f` / `--formats` as a JSON array (for example `'["woff2"]'`) or as a comma-separated list (for example `woff2` or `svg, ttf, woff2`). Invalid format names throw an error.
 - API and config files: `formats` must be an array of the values above; unknown names (for example `icon`) throw before the pipeline runs.
@@ -344,7 +410,7 @@ Notes:
 
 - Type: `string`
 - Default: Same as [`fontName`](#fontname) when not set.
-- Description: CSS `font-family` name emitted by built-in templates (`fontFamily` in Nunjucks context). Output **font files** are always named after `fontName` (for example `icons-a.woff2`); built-in templates reference those files with `{{ fontName }}` in `url(...)` while `font-family` uses `{{ fontFamily }}` ([#331](https://github.com/itgalaxy/webfont/issues/331)).
+- Description: CSS `font-family` name emitted by built-in templates (`fontFamily` in Nunjucks context). Output **font files** are always named after `fontName` (for example `icons-a.woff2`); built-in templates reference those files with Nunjucks `fontName` / `fontFamily` placeholders in `url(...)` and `font-family` ([#331](https://github.com/itgalaxy/webfont/issues/331)).
 
 #### `templateCacheString`
 
@@ -860,6 +926,7 @@ The CLI can exit the process with the following exit codes:
 - [ttf2eot](https://github.com/fontello/ttf2eot) - Converts TTF fonts to EOT format.
 - [ttf2woff](https://github.com/fontello/ttf2woff) - Converts TTF fonts to WOFF format.
 - [wawoff2](https://github.com/fontello/wawoff2) - Converts TTF fonts to WOFF2 and versa vice.
+- [fontTools](https://github.com/fonttools/fonttools) - Complementary low-level font toolkit (Python) for jobs webfont does not cover: subsetting, variable fonts, OpenType feature compilation, table editing, and TTX (font ⇄ XML). Generate the font with webfont, then inspect or optimize it with fontTools.
 
 ## Roadmap
 
@@ -875,7 +942,7 @@ Feel free to push your code if you agree with publishing under the MIT license.
 
 Check our [Changelog](CHANGELOG.md)
 
-## Legal notice
+## Legal Notices
 
 Copyright, disclaimers, font licensing expectations (including WOFF/WOFF2 decompression), community attribution guidelines, and third-party open-source dependencies are documented in **[NOTICE.md](./NOTICE.md)**.