fontaine 0.8.0 → 0.8.2

package/README.md

@@ -135,6 +135,34 @@ If your custom font is used through the mechanism of CSS variables, you'll need
 
 Behind the scenes, there is a 'Poppins fallback' `@font-face` rule that has been created by fontaine. By manually adding this fallback font family to our CSS variable, we make our site use the fallback `@font-face` rule with the correct font metrics that fontaine generates.
 
+## Using Sass, Less or Stylus
+
+The bundler plugin runs before your preprocessor, so it only sees the raw source of files your bundler treats as modules. If your `@font-face` rules live in a Sass partial, are generated by a mixin, or are pulled in with a Sass `@import`, fontaine never sees them: Sass inlines all of that before the bundler does.
+
+For these setups, use the PostCSS plugin instead. It runs over fully-compiled CSS, so `@font-face` rules and `font-family` values are already plain CSS by the time fontaine reads them.
+
+```js
+// postcss.config.js
+module.exports = {
+  plugins: [
+    require('fontaine/postcss')({
+      fallbacks: ['BlinkMacSystemFont', 'Segoe UI', 'Helvetica Neue', 'Arial', 'Noto Sans'],
+    }),
+    // ...any other plugins, such as autoprefixer or cssnano
+  ],
+}
+```
+
+It accepts the same `fallbacks`, `categoryFallbacks`, `resolvePath`, `skipFontFaceGeneration` and `fallbackName` options as the bundler plugin. Do not use both plugins at once.
+
+A couple of things worth checking in a webpack setup:
+
+- Enable source maps on `sass-loader`. Sass does not rebase the URLs it inlines, so fontaine uses the source map to work out which stylesheet a `src` URL was written relative to. Without it, relative font paths are resolved against the entrypoint and metrics cannot be read.
+- Set `importLoaders` on `css-loader` (`2` for `postcss-loader` + `sass-loader`) if you import CSS that contains `@font-face` rules, such as Fontsource packages. Otherwise `css-loader` resolves those imports without running them through `postcss-loader`, and fontaine never sees them.
+
+> [!NOTE]
+> Because a `font-family` declaration and the `@font-face` rule it refers to may end up in different stylesheets, the PostCSS plugin appends a fallback to every non-generic `font-family` it finds, whether or not it generated the matching `@font-face` rule itself. A fallback family with no `@font-face` rule is ignored by the browser.
+
 ## Category-Aware Fallbacks
 
 Fontaine automatically selects appropriate fallback fonts based on font categories (serif, sans-serif, monospace, etc.) when using object-based fallback configuration.
@@ -242,10 +270,10 @@ Published under [MIT License](./LICENCE).
 
 <!-- Badges -->
 
-[npm-version-src]: https://img.shields.io/npm/v/fontaine?style=flat-square
-[npm-version-href]: https://npmjs.com/package/fontaine
-[npm-downloads-src]: https://img.shields.io/npm/dm/fontaine?style=flat-square
-[npm-downloads-href]: https://npmjs.com/package/fontaine
+[npm-version-src]: https://npmx.dev/api/registry/badge/version/fontaine
+[npm-version-href]: https://npmx.dev/package/fontaine
+[npm-downloads-src]: https://npmx.dev/api/registry/badge/downloads/fontaine
+[npm-downloads-href]: https://npmx.dev/package/fontaine
 [github-actions-src]: https://img.shields.io/github/actions/workflow/status/unjs/fontaine/ci.yml?branch=main&style=flat-square
 [github-actions-href]: https://github.com/unjs/fontaine/actions/workflows/ci.yml
 [codecov-src]: https://img.shields.io/codecov/c/gh/unjs/fontaine/main?style=flat-square