webfont 12.4.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

@@ -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)
 
 ---
@@ -351,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`
 
@@ -867,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
 
@@ -882,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)**.
 

package/dist/cli.mjs

@@ -28,7 +28,7 @@ import { Readable as _e } from "stream";
 import ve from "svg2ttf";
 //#region package.json
 var p, ye, be, xe, Se, Ce, we, Te, Ee, De, m, h, g, _, v, y, b, x, S, C, w, T, E, Oe, ke, Ae, je = r((() => {
-	p = "webfont", ye = "12.4.0", be = "Generator of fonts from SVG icons; decompress WOFF/WOFF2 to embedded TTF/OTF (not TTF↔OTF transcoding)", xe = {
+	p = "webfont", ye = "12.4.1", be = "Generator of fonts from SVG icons; decompress WOFF/WOFF2 to embedded TTF/OTF (not TTF↔OTF transcoding)", xe = {
 		lib: "dist",
 		source: "src"
 	}, Se = [
@@ -65,6 +65,12 @@ var p, ye, be, xe, Se, Ce, we, Te, Ee, De, m, h, g, _, v, y, b, x, S, C, w, T, E
 		build: "vite build --mode library && vite build --mode library-esm && vite build --mode browser && vite build --mode cli && node scripts/emit-mts-types.mjs",
 		clean: "rm -rf dist/ temp/",
 		demo: "node dist/cli.mjs './src/fixtures/svg-icons/*.svg' -d demo -t html --normalize --center-horizontally",
+		"docs:build": "npm run build && npm run docs:site",
+		"docs:demo": "node dist/cli.mjs './src/fixtures/svg-icons/*.svg' -d public/font-demo -t html --normalize --center-horizontally --dest-create",
+		"predocs:site": "node -e \"require('node:fs').existsSync('dist/cli.mjs')||require('node:child_process').execSync('npm run build',{stdio:'inherit'})\"",
+		"docs:site": "npm run docs:demo && vitepress build",
+		"docs:dev": "vitepress dev",
+		"docs:preview": "vitepress preview",
 		lint: "biome check .",
 		"lint:suppressions": "node scripts/check-no-suppressions.mjs",
 		typecheck: "tsc -p tsconfig.json --noEmit",
@@ -124,6 +130,7 @@ var p, ye, be, xe, Se, Ce, we, Te, Ee, De, m, h, g, _, v, y, b, x, S, C, w, T, E
 		vite: "8.1.3",
 		"vite-plugin-checker": "0.14.4",
 		"vite-plugin-dts": "5.0.3",
+		vitepress: "1.6.4",
 		vitest: "4.1.9"
 	}, x = {
 		minimatch: "10.2.5",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webfont",
-  "version": "12.4.0",
+  "version": "12.4.1",
   "description": "Generator of fonts from SVG icons; decompress WOFF/WOFF2 to embedded TTF/OTF (not TTF↔OTF transcoding)",
   "directories": {
     "lib": "dist",
@@ -51,6 +51,12 @@
     "build": "vite build --mode library && vite build --mode library-esm && vite build --mode browser && vite build --mode cli && node scripts/emit-mts-types.mjs",
     "clean": "rm -rf dist/ temp/",
     "demo": "node dist/cli.mjs './src/fixtures/svg-icons/*.svg' -d demo -t html --normalize --center-horizontally",
+    "docs:build": "npm run build && npm run docs:site",
+    "docs:demo": "node dist/cli.mjs './src/fixtures/svg-icons/*.svg' -d public/font-demo -t html --normalize --center-horizontally --dest-create",
+    "predocs:site": "node -e \"require('node:fs').existsSync('dist/cli.mjs')||require('node:child_process').execSync('npm run build',{stdio:'inherit'})\"",
+    "docs:site": "npm run docs:demo && vitepress build",
+    "docs:dev": "vitepress dev",
+    "docs:preview": "vitepress preview",
     "lint": "biome check .",
     "lint:suppressions": "node scripts/check-no-suppressions.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
@@ -112,6 +118,7 @@
     "vite": "8.1.3",
     "vite-plugin-checker": "0.14.4",
     "vite-plugin-dts": "5.0.3",
+    "vitepress": "1.6.4",
     "vitest": "4.1.9"
   },
   "overrides": {