feat(fonts): merge families (#12696)

Co-authored-by: Sarah Rainsberger <[email protected]>

Author: florian-lefebvre

src/content/docs/en/reference/experimental-flags/fonts.mdx

@@ -507,7 +507,7 @@ optimizedFallbacks: false
 
 ### Remote font properties
 
-Further configuration options are available for remote fonts. Set these to customize the data loaded from your [font provider](#available-remote-font-providers), for example to only download certain font weights or styles.
+Further configuration options are available for remote fonts. Set these to customize the data loaded from your [font provider](#available-remote-font-providers), for example to only download certain font weights or styles. For more control, more [granular configuration](#granular-remote-font-configuration) is available.
 
 Under the hood, these options are handled by [unifont](https://github.com/unjs/unifont/). Some properties may not be supported by some providers and may be handled differently by each provider.
 
@@ -787,6 +787,43 @@ export default defineConfig({
 });
 ```
 
+## Granular remote font configuration
+
+<p>
+
+<Since v="5.15.6" />
+</p>
+
+A font family is defined by a combination of properties such as weights and styles (e.g. `weights: [500, 600]` and `styles: ["normal", "bold"]`), but you may want to download only certain combinations of these.
+
+For greater control over which font files are downloaded, you can specify the same font (ie. with the same `cssVariable`, `name`, and `provider` properties) multiple times with different combinations. Astro will merge the results and download only the required files. For example, it is possible to download normal `500` and `600` while downloading only italic `500`:
+
+```js
+// astro.config.mjs
+import { defineConfig, fontProviders } from "astro/config"
+
+export default defineConfig({
+  experimental: {
+    fonts: [
+      {
+        name: "Roboto",
+        cssVariable: "--roboto",
+        provider: fontProviders.google(),
+        weights: [500, 600],
+        styles: ["normal"]
+      },
+      {
+        name: "Roboto",
+        cssVariable: "--roboto",
+        provider: fontProviders.google(),
+        weights: [500],
+        styles: ["italic"]
+      }
+    ]
+  }
+})
+```
+
 ## Build your own font provider
 
 If you do not wish to use one of the [built-in providers](#available-remote-font-providers) (eg. you want to use a 3rd-party unifont provider or build something for a private registry), you can build your own.