From d0a23dc2de38846fc63aca1d98e4772e19b823f1 Mon Sep 17 00:00:00 2001
From: Armand Philippot <git@armand.philippot.eu>
Date: Fri, 3 Apr 2026 16:10:54 +0200
Subject: [PATCH 01/13] fix: expand the `fontData` guide with a working example

Closes #13635
---
 src/content/docs/en/guides/fonts.mdx | 38 ++++++++++++++++++++++------
 1 file changed, 30 insertions(+), 8 deletions(-)

diff --git a/src/content/docs/en/guides/fonts.mdx b/src/content/docs/en/guides/fonts.mdx
index 9e4befe47d890..7d98a4b1b5610 100644
--- a/src/content/docs/en/guides/fonts.mdx
+++ b/src/content/docs/en/guides/fonts.mdx
@@ -178,16 +178,31 @@ See [Tailwind's docs on adding custom font families](https://tailwindcss.com/doc
 
 ## Accessing font data programmatically
 
-The [`fontData`](/en/reference/modules/astro-assets/#fontdata) object allows you to retrieve lower-level font family data programmatically. For example, you can use it in an [API Route](/en/guides/endpoints/#server-endpoints-api-routes) to generate OpenGraph images using [satori](https://github.com/vercel/satori), combined with proper [formats](/en/reference/configuration-reference/#fontformats) configuration:
+Astro exposes a low-level API for accessing font family data programmatically through the [`fontData`](/en/reference/modules/astro-assets/#fontdata) object. This can be useful for advanced use cases where you need direct access to font files, such as generating OpenGraph images with [satori](https://github.com/vercel/satori) in an [API Route](/en/guides/endpoints/#server-endpoints-api-routes).
+
+This low-level API gives you access to all font files downloaded by Astro for your project, along with their metadata. This means that you are responsible for filtering font files to find the specific file you need, and for resolving the file path to use based on the build output structure.
+
+The following example generates an OpenGraph image in a static file endpoint, assuming that only one font has been configured with a [format supported by Satori](https://github.com/vercel/satori?tab=readme-ov-file#fonts):
 
 ```tsx title="src/pages/og.png.ts" {2} "fontData[\"--font-roboto\"]"
-import type{ APIRoute } from "astro";
+import type { APIRoute } from "astro";
 import { fontData } from "astro:assets";
+import { outDir } from "astro:config/server";
+import { readFile } from "node:fs/promises";
 import satori from "satori";
 import { html } from "satori-html";
+import sharp from "sharp";
 
 export const GET: APIRoute = async (context) => {
-  const data = fontData["--font-roboto"];
+  const fontPath = fontData["--font-roboto"][0]?.src[0]?.url;
+
+  if (fontPath === undefined) {
+    throw new Error("Cannot find the font path.");
+  }
+
+  const data = import.meta.env.DEV
+    ? await fetch(new URL(fontPath, context.url.origin)).then(async (res) => res.arrayBuffer())
+    : await readFile(new URL(`.${fontPath}`, outDir));
 
   const svg = await satori(
     html`<div style="color: black;">hello, world</div>`,
@@ -197,9 +212,7 @@ export const GET: APIRoute = async (context) => {
       fonts: [
         {
           name: "Roboto",
-          data: await fetch(
-            new URL(data[0].src[0].url, context.url.origin),
-          ).then((res) => res.arrayBuffer()),
+          data,
           weight: 400,
           style: "normal",
         },
@@ -207,8 +220,17 @@ export const GET: APIRoute = async (context) => {
     },
   );
 
-  // ...
-}
+  const pngBuffer = await sharp(Buffer.from(svg))
+    .resize(600, 400)
+    .png()
+    .toBuffer();
+
+  return new Response(new Uint8Array(pngBuffer), {
+    headers: {
+      "Content-Type": "image/png",
+    },
+  });
+};
 ```
 
 ## Granular font configuration

From 1b547a9dad8d201c2701c30f92775264fa845a00 Mon Sep 17 00:00:00 2001
From: Armand Philippot <git@armand.philippot.eu>
Date: Fri, 3 Apr 2026 16:12:23 +0200
Subject: [PATCH 02/13] feat: expand the `FontData` type description

---
 .../en/reference/modules/astro-assets.mdx     | 27 +++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/src/content/docs/en/reference/modules/astro-assets.mdx b/src/content/docs/en/reference/modules/astro-assets.mdx
index 3d392d12bd1ed..f10ea2c2483c6 100644
--- a/src/content/docs/en/reference/modules/astro-assets.mdx
+++ b/src/content/docs/en/reference/modules/astro-assets.mdx
@@ -755,6 +755,33 @@ Describes the [properties of a remote image](#image-). This ensures that when [`
 
 Describes the font data associated with a given font family.
 
+#### `FontData.src`
+
+<p>
+
+**Type:** `Array<{ url: string; format?: string; tech?: string }>`
+</p>
+
+An array of objects describing the available font files for a given font family. Each object contains a `url` and, optionally, the associated [`format`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/src#font_formats) and [`tech`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/src#font_technologies).
+
+#### `FontData.weight`
+
+<p>
+
+**Type:** `string`
+</p>
+
+Specifies the font weight (e.g. `400`, `600`).
+
+#### `FontData.style`
+
+<p>
+
+**Type:** `string`
+</p>
+
+Specifies the font style (e.g. `normal`, `italic`).
+
 ## Imports from `astro/assets`
 
 The following helpers are imported from the regular assets module:

From 6ff40599683e0c482d705aefa9f23205847e1d8f Mon Sep 17 00:00:00 2001
From: Armand Philippot <git@armand.philippot.eu>
Date: Fri, 3 Apr 2026 17:35:57 +0200
Subject: [PATCH 03/13] feat: add a section for using variable fonts

---
 src/content/docs/en/guides/fonts.mdx | 55 ++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)

diff --git a/src/content/docs/en/guides/fonts.mdx b/src/content/docs/en/guides/fonts.mdx
index 7d98a4b1b5610..be6308d93ad0e 100644
--- a/src/content/docs/en/guides/fonts.mdx
+++ b/src/content/docs/en/guides/fonts.mdx
@@ -175,6 +175,61 @@ Instead, after [configuring your custom font](#configuring-custom-fonts) and [ad
 
 See [Tailwind's docs on adding custom font families](https://tailwindcss.com/docs/font-family#using-a-custom-value) for more information.
 
+## Using variable fonts
+
+To use [variable fonts](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_fonts/Variable_fonts_guide) in your project, you can specify the range of available weights for the font instead of individual weights in your provider's configuration.
+
+<Tabs>
+<TabItem label="With a provider">
+
+When [using a font provider](#using-fontsource) that supports variable fonts, you can specify that the variable version of a font should be downloaded by setting the [`weights` property](/en/reference/configuration-reference/#fontweights) with an array containing the exact range of weights available for the font.
+
+The following example downloads [Fira Code from Fontsource](https://fontsource.org/fonts/fira-code) as a variable font with the available weight range:
+
+```js title="astro.config.mjs" {9}
+import { defineConfig, fontProviders } from "astro/config";
+
+export default defineConfig({
+  fonts: [{
+    cssVariable: "--font-fira-code",
+    name: "Fira Code",
+    provider: fontProviders.fontsource(),
+    styles: ["normal"],
+    weights: ["300 700"],
+  }]
+});
+```
+
+</TabItem>
+<TabItem label="With a local font file">
+
+When [using a local font file](#using-a-local-font-file), you can specify that the font is variable by setting the [`weight` property of the variant](/en/reference/font-provider-reference/#weight) to a string corresponding to the exact weight range available for the font.
+
+The following example configures Inter as a local variable font with the available weight range:
+
+```js title="astro.config.mjs" {11}
+import { defineConfig, fontProviders } from "astro/config";
+
+export default defineConfig({
+  fonts: [{
+    provider: fontProviders.local(),
+    name: "Inter",
+    cssVariable: "--font-inter",
+    options: {
+      variants: [
+        {
+          weight: "100 900",
+          style: "normal",
+          src: ["./src/assets/fonts/InterVariable.woff2"],
+        },
+      ],
+    },
+  }]
+});
+```
+
+</TabItem>
+</Tabs>
 
 ## Accessing font data programmatically
 

From f8355d43d9169868308cf4cdeb407b486fda2892 Mon Sep 17 00:00:00 2001
From: Armand Philippot <git@armand.philippot.eu>
Date: Fri, 3 Apr 2026 18:31:51 +0200
Subject: [PATCH 04/13] feat: add a section for preloading fonts

---
 src/content/docs/en/guides/fonts.mdx | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/src/content/docs/en/guides/fonts.mdx b/src/content/docs/en/guides/fonts.mdx
index be6308d93ad0e..7eb638ecea314 100644
--- a/src/content/docs/en/guides/fonts.mdx
+++ b/src/content/docs/en/guides/fonts.mdx
@@ -133,6 +133,27 @@ After [a font is configured](#configuring-custom-fonts), it must be added to you
 
 </Steps>
 
+### Preloading fonts
+
+Font preloading should be done judiciously, as it can block the loading of other important resources or download fonts unnecessary for the current page. Consider preloading only the most essential fonts, necessary for displaying content visible above the fold.
+
+To preload a font, pass the [`preload` property](/en/reference/modules/astro-assets/#preload) to the corresponding `<Font />` component. If multiple files correspond to a font, you can also specify which one to preload by passing an object describing the font.
+
+```astro title="src/layouts/Layout.astro" {7}
+---
+import { Font } from "astro:assets";
+---
+
+<html>
+  <head>
+    <Font cssVariable="--font-distant-galaxy" preload />
+  </head>
+  <body>
+    <slot />
+  </body>
+</html>
+```
+
 ## Register fonts in Tailwind
 
 If you are using [Tailwind](/en/guides/styling/#tailwind) for styling, you will not apply your styles with the `font-face` CSS property.

From 38579df03cf5450f61c46d9b88f2eb668f88fa73 Mon Sep 17 00:00:00 2001
From: Armand Philippot <git@armand.philippot.eu>
Date: Mon, 6 Apr 2026 14:25:55 +0200
Subject: [PATCH 05/13] link to the GitHub issue related to fontData

---
 src/content/docs/en/guides/fonts.mdx | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/src/content/docs/en/guides/fonts.mdx b/src/content/docs/en/guides/fonts.mdx
index 7eb638ecea314..ce26dd61898b6 100644
--- a/src/content/docs/en/guides/fonts.mdx
+++ b/src/content/docs/en/guides/fonts.mdx
@@ -258,6 +258,12 @@ Astro exposes a low-level API for accessing font family data programmatically th
 
 This low-level API gives you access to all font files downloaded by Astro for your project, along with their metadata. This means that you are responsible for filtering font files to find the specific file you need, and for resolving the file path to use based on the build output structure.
 
+:::note
+The current API has a [known limitation that requires you to manually load the font file](https://github.com/withastro/astro/issues/16139) from the output path at build time.
+
+A new API is being developed to simplify this process and will be available in a future release. You can subscribe to the GitHub issue to follow the progress and be notified of its release.
+:::
+
 The following example generates an OpenGraph image in a static file endpoint, assuming that only one font has been configured with a [format supported by Satori](https://github.com/vercel/satori?tab=readme-ov-file#fonts):
 
 ```tsx title="src/pages/og.png.ts" {2} "fontData[\"--font-roboto\"]"

From dffd5d217543b7ccc4a9c001f35bd9a2e108619c Mon Sep 17 00:00:00 2001
From: Armand Philippot <git@armand.philippot.eu>
Date: Mon, 6 Apr 2026 15:40:49 +0200
Subject: [PATCH 06/13] add a fallback fonts section

---
 src/content/docs/en/guides/fonts.mdx | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/src/content/docs/en/guides/fonts.mdx b/src/content/docs/en/guides/fonts.mdx
index ce26dd61898b6..55444d6d7bf7a 100644
--- a/src/content/docs/en/guides/fonts.mdx
+++ b/src/content/docs/en/guides/fonts.mdx
@@ -252,6 +252,27 @@ export default defineConfig({
 </TabItem>
 </Tabs>
 
+## Customizing font fallbacks
+
+Fallback fonts are used when the primary font has not yet loaded, contains missing characters, or cannot be loaded for any reason. When the fallback font differs significantly from the primary font, layout shifts may occur. To avoid this, Astro automatically generates optimized fallback fonts by default using font metrics and the generic `sans-serif` font family.
+
+The default fallback font was chosen to work correctly with most fonts, but it may not match the desired appearance of your primary font. You can [define your own custom fallback fonts in your font configuration](/en/reference/configuration-reference/#fontfallbacks):
+
+```mjs title="astro.config.mjs" {8}
+import { defineConfig, fontProviders } from "astro/config";
+
+export default defineConfig({
+  fonts: [{
+    provider: fontProviders.fontsource(),
+    name: "Cousine",
+    cssVariable: "--font-cousine",
+    fallbacks: ["monospace"]
+  }]
+});
+```
+
+You can also opt out of the default optimization by setting [`font.optimizedFallbacks`](/en/reference/configuration-reference/#fontoptimizedfallbacks) to `false` in your font configuration. Astro will then use the fallback fonts specified in your configuration without any additional automatic processing.
+
 ## Accessing font data programmatically
 
 Astro exposes a low-level API for accessing font family data programmatically through the [`fontData`](/en/reference/modules/astro-assets/#fontdata) object. This can be useful for advanced use cases where you need direct access to font files, such as generating OpenGraph images with [satori](https://github.com/vercel/satori) in an [API Route](/en/guides/endpoints/#server-endpoints-api-routes).

From 41b0ef755e3480ed3b60c07ea6a8e240b291b288 Mon Sep 17 00:00:00 2001
From: Armand Philippot <git@armand.philippot.eu>
Date: Mon, 6 Apr 2026 16:46:00 +0200
Subject: [PATCH 07/13] first pass of improvements, thanks!

Co-authored-by: Florian Lefebvre <contact@florian-lefebvre.dev>
---
 src/content/docs/en/guides/fonts.mdx | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/content/docs/en/guides/fonts.mdx b/src/content/docs/en/guides/fonts.mdx
index 55444d6d7bf7a..5678b28336feb 100644
--- a/src/content/docs/en/guides/fonts.mdx
+++ b/src/content/docs/en/guides/fonts.mdx
@@ -137,7 +137,7 @@ After [a font is configured](#configuring-custom-fonts), it must be added to you
 
 Font preloading should be done judiciously, as it can block the loading of other important resources or download fonts unnecessary for the current page. Consider preloading only the most essential fonts, necessary for displaying content visible above the fold.
 
-To preload a font, pass the [`preload` property](/en/reference/modules/astro-assets/#preload) to the corresponding `<Font />` component. If multiple files correspond to a font, you can also specify which one to preload by passing an object describing the font.
+To preload a font, pass the [`preload` property](/en/reference/modules/astro-assets/#preload) to the corresponding `<Font />` component. If multiple files correspond to a font, you can also specify which one to preload by passing an array.
 
 ```astro title="src/layouts/Layout.astro" {7}
 ---
@@ -254,9 +254,9 @@ export default defineConfig({
 
 ## Customizing font fallbacks
 
-Fallback fonts are used when the primary font has not yet loaded, contains missing characters, or cannot be loaded for any reason. When the fallback font differs significantly from the primary font, layout shifts may occur. To avoid this, Astro automatically generates optimized fallback fonts by default using font metrics and the generic `sans-serif` font family.
-
-The default fallback font was chosen to work correctly with most fonts, but it may not match the desired appearance of your primary font. You can [define your own custom fallback fonts in your font configuration](/en/reference/configuration-reference/#fontfallbacks):
+Fallback fonts are used when the primary font has not yet loaded, contains missing characters, or cannot be loaded for any reason. When the fallback font differs significantly from the primary font, layout shifts may occur during page loading. 
+
+To avoid this, Astro automatically tries to generate optimized fallback fonts from the last [defined fallback](/en/reference/configuration-reference/#fontfallbacks), if it is a [generic font family](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/font-family#generic-name). It uses `sans-serif` by default but it may not match the desired appearance of your primary font. You can adjust it in your font configuration:
 
 ```mjs title="astro.config.mjs" {8}
 import { defineConfig, fontProviders } from "astro/config";
@@ -282,7 +282,7 @@ This low-level API gives you access to all font files downloaded by Astro for yo
 :::note
 The current API has a [known limitation that requires you to manually load the font file](https://github.com/withastro/astro/issues/16139) from the output path at build time.
 
-A new API is being developed to simplify this process and will be available in a future release. You can subscribe to the GitHub issue to follow the progress and be notified of its release.
+A new API is being developed to simplify this process and will be available in a future release. You can subscribe to the GitHub issue to follow its progress.
 :::
 
 The following example generates an OpenGraph image in a static file endpoint, assuming that only one font has been configured with a [format supported by Satori](https://github.com/vercel/satori?tab=readme-ov-file#fonts):

From dbb79ed73b5bf0175c15ae8a4aa86862788be199 Mon Sep 17 00:00:00 2001
From: Armand Philippot <git@armand.philippot.eu>
Date: Mon, 6 Apr 2026 21:19:42 +0200
Subject: [PATCH 08/13] thanks Yan!

Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com>
---
 src/content/docs/en/guides/fonts.mdx | 874 +++++++++++++--------------
 1 file changed, 437 insertions(+), 437 deletions(-)

diff --git a/src/content/docs/en/guides/fonts.mdx b/src/content/docs/en/guides/fonts.mdx
index 5678b28336feb..e1aaf52b384c2 100644
--- a/src/content/docs/en/guides/fonts.mdx
+++ b/src/content/docs/en/guides/fonts.mdx
@@ -1,441 +1,441 @@
----
-title: Using custom fonts
-sidebar:
-  label: Fonts
-description: >-
-  Looking to add some custom typefaces to an Astro website? Use Google Fonts
-  with Fontsource or add a font of your choice.
-i18nReady: true
----
-import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
-import ReadMore from '~/components/ReadMore.astro';
-import { Steps, Tabs, TabItem } from '@astrojs/starlight/components';
-
-This guide will show you how to add [web fonts](https://developer.mozilla.org/en-US/docs/Learn/CSS/Styling_text/Web_fonts) to your project and use them in your components.
-
-Astro provides a way to use fonts from your filesystem and various font providers (e.g. Fontsource, Google) through a unified, [fully customizable](/en/reference/configuration-reference/#fonts), and type-safe API.
-
-Web fonts can impact page performance at both load time and rendering time. This API helps you keep your site performant with automatic [web font optimizations](https://web.dev/learn/performance/optimize-web-fonts) including preload links, optimized fallbacks, and opinionated defaults. [See common usage examples](#examples).
-
-The Fonts API focuses on performance and privacy by downloading and caching fonts so they're served from your site. This can avoid sending user data to third-party sites, and also ensures that a consistent set of fonts is available to all your visitors.
-
-## Configuring custom fonts
-
-Registering custom fonts for your Astro project is done through [the `fonts` option](/en/reference/configuration-reference/#fonts) in your Astro config.
-
-For each font you want to use, you must specify its [name](/en/reference/configuration-reference/#fontname), a [CSS variable](/en/reference/configuration-reference/#fontcssvariable), and an Astro font provider.
-
-Astro provides [built-in support for the most popular font providers](/en/reference/font-provider-reference/#built-in-providers): Adobe, Bunny, Fontshare, Fontsource, Google, Google Icons and NPM, as well as for using your own local font files. Additionally, you can [further customize your font configuration](#granular-font-configuration) to optimize performance and visitor experience.
-
-
-### Using a local font file
-
-This example will demonstrate adding a custom font using the font file `DistantGalaxy.woff2`.
-
-<Steps>
-
-1. Add your font file inside the [`src/` directory](/en/basics/project-structure/#src), for example `src/assets/fonts/`.
-
-2. Create a new font family in your Astro config file using the [local font provider](/en/reference/font-provider-reference/#local) and specify the variants to be included:
-
-    ```js title="astro.config.mjs"
-    import { defineConfig, fontProviders } from "astro/config";
-
-    export default defineConfig({
-      fonts: [{
-        provider: fontProviders.local(),
-        name: "DistantGalaxy",
-        cssVariable: "--font-distant-galaxy",
-        options: {
-          variants: [{
-            src: ['./src/assets/fonts/DistantGalaxy.woff2'],
-            weight: 'normal',
-            style: 'normal'
-          }]
-        }
-      }]
-    });
-    ```
-3. Your font is now configured and ready to be [added to your page head](#applying-custom-fonts) so that it can be used in your project.
-
-</Steps>
-
-### Using Fontsource
-
-Astro supports [several font providers](/en/reference/font-provider-reference/#built-in-providers) out of the box, including support for [Fontsource](https://fontsource.org/) that simplifies using Google Fonts and other open-source fonts.
-
-The following example will use Fontsource to add custom font support, but the process is similar for any of Astro's built-in font providers (e.g. [Adobe](https://fonts.adobe.com/), [Bunny](https://fonts.bunny.net/)).
-
-<Steps>
-
-1. Find the font you want to use in [Fontsource's catalog](https://fontsource.org/). This example will use [Roboto](https://fontsource.org/fonts/roboto).
-
-2. Create a new font family in your Astro config file using the [Fontsource provider](/en/reference/font-provider-reference/#fontsource):
-
-    ```js title="astro.config.mjs"
-    import { defineConfig, fontProviders } from "astro/config";
-
-    export default defineConfig({
-      fonts: [{
-        provider: fontProviders.fontsource(),
-        name: "Roboto",
-        cssVariable: "--font-roboto",
-      }]
-    });
-    ```
-3. Your font is now configured and ready to be [added to your page head](#applying-custom-fonts) so that it can be used in your project.
-
-</Steps>
-
-## Applying custom fonts
-
-After [a font is configured](#configuring-custom-fonts), it must be added to your page head with an identifying CSS variable. Then, you can use this variable when defining your page styles.
-
-<Steps>
-
-1. Import and include the [`<Font />`](/en/reference/modules/astro-assets/#font-) component with the required `cssVariable` property in the head of your page, usually in a dedicated `Head.astro` component or in a [layout](/en/basics/layouts/) component directly:
-
-    ```astro title="src/layouts/Layout.astro" ins={2,7}
-    ---
-    import { Font } from "astro:assets";
-    ---
-
-    <html>
-      <head>
-        <Font cssVariable="--font-distant-galaxy" />
-      </head>
-      <body>
-        <slot />
-      </body>
-    </html>
-    ```
-
-2. In any page rendered with that layout, including the layout component itself, you can now define styles with your font's `cssVariable` to apply your custom font.
-
-    In the following example, the `<h1>` heading will have the custom font applied, while the paragraph `<p>` will not.
-
-    ```astro title="src/pages/example.astro" ins={10-12}
-    ---
-    import Layout from "../layouts/Layout.astro";
-    ---
-    <Layout>
-      <h1>In a galaxy far, far away...</h1>
-
-      <p>Custom fonts make my headings much cooler!</p>
-
-      <style>
-      h1 {
-        font-family: var(--font-distant-galaxy);
-      }
-      </style>
-    </Layout>
-    ```
-
-</Steps>
-
-### Preloading fonts
-
-Font preloading should be done judiciously, as it can block the loading of other important resources or download fonts unnecessary for the current page. Consider preloading only the most essential fonts, necessary for displaying content visible above the fold.
-
+---
+title: Using custom fonts
+sidebar:
+  label: Fonts
+description: >-
+  Looking to add some custom typefaces to an Astro website? Use Google Fonts
+  with Fontsource or add a font of your choice.
+i18nReady: true
+---
+import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
+import ReadMore from '~/components/ReadMore.astro';
+import { Steps, Tabs, TabItem } from '@astrojs/starlight/components';
+
+This guide will show you how to add [web fonts](https://developer.mozilla.org/en-US/docs/Learn/CSS/Styling_text/Web_fonts) to your project and use them in your components.
+
+Astro provides a way to use fonts from your filesystem and various font providers (e.g. Fontsource, Google) through a unified, [fully customizable](/en/reference/configuration-reference/#fonts), and type-safe API.
+
+Web fonts can impact page performance at both load time and rendering time. This API helps you keep your site performant with automatic [web font optimizations](https://web.dev/learn/performance/optimize-web-fonts) including preload links, optimized fallbacks, and opinionated defaults. [See common usage examples](#examples).
+
+The Fonts API focuses on performance and privacy by downloading and caching fonts so they're served from your site. This can avoid sending user data to third-party sites, and also ensures that a consistent set of fonts is available to all your visitors.
+
+## Configuring custom fonts
+
+Registering custom fonts for your Astro project is done through [the `fonts` option](/en/reference/configuration-reference/#fonts) in your Astro config.
+
+For each font you want to use, you must specify its [name](/en/reference/configuration-reference/#fontname), a [CSS variable](/en/reference/configuration-reference/#fontcssvariable), and an Astro font provider.
+
+Astro provides [built-in support for the most popular font providers](/en/reference/font-provider-reference/#built-in-providers): Adobe, Bunny, Fontshare, Fontsource, Google, Google Icons and NPM, as well as for using your own local font files. Additionally, you can [further customize your font configuration](#granular-font-configuration) to optimize performance and visitor experience.
+
+
+### Using a local font file
+
+This example will demonstrate adding a custom font using the font file `DistantGalaxy.woff2`.
+
+<Steps>
+
+1. Add your font file inside the [`src/` directory](/en/basics/project-structure/#src), for example `src/assets/fonts/`.
+
+2. Create a new font family in your Astro config file using the [local font provider](/en/reference/font-provider-reference/#local) and specify the variants to be included:
+
+    ```js title="astro.config.mjs"
+    import { defineConfig, fontProviders } from "astro/config";
+
+    export default defineConfig({
+      fonts: [{
+        provider: fontProviders.local(),
+        name: "DistantGalaxy",
+        cssVariable: "--font-distant-galaxy",
+        options: {
+          variants: [{
+            src: ['./src/assets/fonts/DistantGalaxy.woff2'],
+            weight: 'normal',
+            style: 'normal'
+          }]
+        }
+      }]
+    });
+    ```
+3. Your font is now configured and ready to be [added to your page head](#applying-custom-fonts) so that it can be used in your project.
+
+</Steps>
+
+### Using Fontsource
+
+Astro supports [several font providers](/en/reference/font-provider-reference/#built-in-providers) out of the box, including support for [Fontsource](https://fontsource.org/) that simplifies using Google Fonts and other open-source fonts.
+
+The following example will use Fontsource to add custom font support, but the process is similar for any of Astro's built-in font providers (e.g. [Adobe](https://fonts.adobe.com/), [Bunny](https://fonts.bunny.net/)).
+
+<Steps>
+
+1. Find the font you want to use in [Fontsource's catalog](https://fontsource.org/). This example will use [Roboto](https://fontsource.org/fonts/roboto).
+
+2. Create a new font family in your Astro config file using the [Fontsource provider](/en/reference/font-provider-reference/#fontsource):
+
+    ```js title="astro.config.mjs"
+    import { defineConfig, fontProviders } from "astro/config";
+
+    export default defineConfig({
+      fonts: [{
+        provider: fontProviders.fontsource(),
+        name: "Roboto",
+        cssVariable: "--font-roboto",
+      }]
+    });
+    ```
+3. Your font is now configured and ready to be [added to your page head](#applying-custom-fonts) so that it can be used in your project.
+
+</Steps>
+
+## Applying custom fonts
+
+After [a font is configured](#configuring-custom-fonts), it must be added to your page head with an identifying CSS variable. Then, you can use this variable when defining your page styles.
+
+<Steps>
+
+1. Import and include the [`<Font />`](/en/reference/modules/astro-assets/#font-) component with the required `cssVariable` property in the head of your page, usually in a dedicated `Head.astro` component or in a [layout](/en/basics/layouts/) component directly:
+
+    ```astro title="src/layouts/Layout.astro" ins={2,7}
+    ---
+    import { Font } from "astro:assets";
+    ---
+
+    <html>
+      <head>
+        <Font cssVariable="--font-distant-galaxy" />
+      </head>
+      <body>
+        <slot />
+      </body>
+    </html>
+    ```
+
+2. In any page rendered with that layout, including the layout component itself, you can now define styles with your font's `cssVariable` to apply your custom font.
+
+    In the following example, the `<h1>` heading will have the custom font applied, while the paragraph `<p>` will not.
+
+    ```astro title="src/pages/example.astro" ins={10-12}
+    ---
+    import Layout from "../layouts/Layout.astro";
+    ---
+    <Layout>
+      <h1>In a galaxy far, far away...</h1>
+
+      <p>Custom fonts make my headings much cooler!</p>
+
+      <style>
+      h1 {
+        font-family: var(--font-distant-galaxy);
+      }
+      </style>
+    </Layout>
+    ```
+
+</Steps>
+
+### Preloading fonts
+
+Font preloading should be done sparingly, as it can block the loading of other important resources or download fonts unnecessary for the current page. Consider preloading only the most essential fonts, necessary for displaying content visible above the fold.
+
 To preload a font, pass the [`preload` property](/en/reference/modules/astro-assets/#preload) to the corresponding `<Font />` component. If multiple files correspond to a font, you can also specify which one to preload by passing an array.
-
-```astro title="src/layouts/Layout.astro" {7}
----
-import { Font } from "astro:assets";
----
-
-<html>
-  <head>
-    <Font cssVariable="--font-distant-galaxy" preload />
-  </head>
-  <body>
-    <slot />
-  </body>
-</html>
-```
-
-## Register fonts in Tailwind
-
-If you are using [Tailwind](/en/guides/styling/#tailwind) for styling, you will not apply your styles with the `font-face` CSS property.
-
-Instead, after [configuring your custom font](#configuring-custom-fonts) and [adding it to your page head](#applying-custom-fonts), you will need to update your Tailwind configuration to register your font:
-
-    <Tabs>
-
-    <TabItem label="Tailwind CSS 4.0">
-
-    ```css title="src/styles/global.css" ins={4} ins="inline"
-    @import "tailwindcss";
-
-    @theme inline {
-      --font-sans: var(--font-roboto);
-    }
-    ```
-
-    </TabItem>
-
-    <TabItem label="Tailwind CSS 3.0">
-
-    ```js title="tailwind.config.mjs" ins={6-8}
-    /** @type {import("tailwindcss").Config} */
-    export default {
-      content: ["./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}"],
-      theme: {
-        extend: {},
-        fontFamily: {
-          sans: ["var(--font-roboto)"]
-        }
-      },
-      plugins: []
-    };
-    ```
-
-    </TabItem>
-
-    </Tabs>
-
-See [Tailwind's docs on adding custom font families](https://tailwindcss.com/docs/font-family#using-a-custom-value) for more information.
-
-## Using variable fonts
-
-To use [variable fonts](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_fonts/Variable_fonts_guide) in your project, you can specify the range of available weights for the font instead of individual weights in your provider's configuration.
-
-<Tabs>
-<TabItem label="With a provider">
-
-When [using a font provider](#using-fontsource) that supports variable fonts, you can specify that the variable version of a font should be downloaded by setting the [`weights` property](/en/reference/configuration-reference/#fontweights) with an array containing the exact range of weights available for the font.
-
-The following example downloads [Fira Code from Fontsource](https://fontsource.org/fonts/fira-code) as a variable font with the available weight range:
-
-```js title="astro.config.mjs" {9}
-import { defineConfig, fontProviders } from "astro/config";
-
-export default defineConfig({
-  fonts: [{
-    cssVariable: "--font-fira-code",
-    name: "Fira Code",
-    provider: fontProviders.fontsource(),
-    styles: ["normal"],
-    weights: ["300 700"],
-  }]
-});
-```
-
-</TabItem>
-<TabItem label="With a local font file">
-
-When [using a local font file](#using-a-local-font-file), you can specify that the font is variable by setting the [`weight` property of the variant](/en/reference/font-provider-reference/#weight) to a string corresponding to the exact weight range available for the font.
-
-The following example configures Inter as a local variable font with the available weight range:
-
-```js title="astro.config.mjs" {11}
-import { defineConfig, fontProviders } from "astro/config";
-
-export default defineConfig({
-  fonts: [{
-    provider: fontProviders.local(),
-    name: "Inter",
-    cssVariable: "--font-inter",
-    options: {
-      variants: [
-        {
-          weight: "100 900",
-          style: "normal",
-          src: ["./src/assets/fonts/InterVariable.woff2"],
-        },
-      ],
-    },
-  }]
-});
-```
-
-</TabItem>
-</Tabs>
-
-## Customizing font fallbacks
-
+
+```astro title="src/layouts/Layout.astro" {7}
+---
+import { Font } from "astro:assets";
+---
+
+<html>
+  <head>
+    <Font cssVariable="--font-distant-galaxy" preload />
+  </head>
+  <body>
+    <slot />
+  </body>
+</html>
+```
+
+## Register fonts in Tailwind
+
+If you are using [Tailwind](/en/guides/styling/#tailwind) for styling, you will not apply your styles with the `font-face` CSS property.
+
+Instead, after [configuring your custom font](#configuring-custom-fonts) and [adding it to your page head](#applying-custom-fonts), you will need to update your Tailwind configuration to register your font:
+
+    <Tabs>
+
+    <TabItem label="Tailwind CSS 4.0">
+
+    ```css title="src/styles/global.css" ins={4} ins="inline"
+    @import "tailwindcss";
+
+    @theme inline {
+      --font-sans: var(--font-roboto);
+    }
+    ```
+
+    </TabItem>
+
+    <TabItem label="Tailwind CSS 3.0">
+
+    ```js title="tailwind.config.mjs" ins={6-8}
+    /** @type {import("tailwindcss").Config} */
+    export default {
+      content: ["./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}"],
+      theme: {
+        extend: {},
+        fontFamily: {
+          sans: ["var(--font-roboto)"]
+        }
+      },
+      plugins: []
+    };
+    ```
+
+    </TabItem>
+
+    </Tabs>
+
+See [Tailwind's docs on adding custom font families](https://tailwindcss.com/docs/font-family#using-a-custom-value) for more information.
+
+## Using variable fonts
+
+To use [variable fonts](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_fonts/Variable_fonts_guide) in your project, you can specify the range of available weights for the font instead of individual weights in your provider's configuration.
+
+<Tabs>
+<TabItem label="With a provider">
+
+When [using a font provider](#using-fontsource) that supports variable fonts, you can specify that the variable version of a font should be downloaded by setting the [`weights` property](/en/reference/configuration-reference/#fontweights) with an array containing the exact range of weights available for the font.
+
+The following example downloads [Fira Code from Fontsource](https://fontsource.org/fonts/fira-code) as a variable font with the available weight range:
+
+```js title="astro.config.mjs" {9}
+import { defineConfig, fontProviders } from "astro/config";
+
+export default defineConfig({
+  fonts: [{
+    cssVariable: "--font-fira-code",
+    name: "Fira Code",
+    provider: fontProviders.fontsource(),
+    styles: ["normal"],
+    weights: ["300 700"],
+  }]
+});
+```
+
+</TabItem>
+<TabItem label="With a local font file">
+
+When [using a local font file](#using-a-local-font-file), you can specify that the font is variable by setting the [`weight` property of the variant](/en/reference/font-provider-reference/#weight) to a string corresponding to the exact weight range available for the font.
+
+The following example configures Inter as a local variable font with the available weight range:
+
+```js title="astro.config.mjs" {11}
+import { defineConfig, fontProviders } from "astro/config";
+
+export default defineConfig({
+  fonts: [{
+    provider: fontProviders.local(),
+    name: "Inter",
+    cssVariable: "--font-inter",
+    options: {
+      variants: [
+        {
+          weight: "100 900",
+          style: "normal",
+          src: ["./src/assets/fonts/InterVariable.woff2"],
+        },
+      ],
+    },
+  }]
+});
+```
+
+</TabItem>
+</Tabs>
+
+## Customizing font fallbacks
+
 Fallback fonts are used when the primary font has not yet loaded, contains missing characters, or cannot be loaded for any reason. When the fallback font differs significantly from the primary font, layout shifts may occur during page loading. 
 
-To avoid this, Astro automatically tries to generate optimized fallback fonts from the last [defined fallback](/en/reference/configuration-reference/#fontfallbacks), if it is a [generic font family](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/font-family#generic-name). It uses `sans-serif` by default but it may not match the desired appearance of your primary font. You can adjust it in your font configuration:
-
-```mjs title="astro.config.mjs" {8}
-import { defineConfig, fontProviders } from "astro/config";
-
-export default defineConfig({
-  fonts: [{
-    provider: fontProviders.fontsource(),
-    name: "Cousine",
-    cssVariable: "--font-cousine",
-    fallbacks: ["monospace"]
-  }]
-});
-```
-
-You can also opt out of the default optimization by setting [`font.optimizedFallbacks`](/en/reference/configuration-reference/#fontoptimizedfallbacks) to `false` in your font configuration. Astro will then use the fallback fonts specified in your configuration without any additional automatic processing.
-
-## Accessing font data programmatically
-
-Astro exposes a low-level API for accessing font family data programmatically through the [`fontData`](/en/reference/modules/astro-assets/#fontdata) object. This can be useful for advanced use cases where you need direct access to font files, such as generating OpenGraph images with [satori](https://github.com/vercel/satori) in an [API Route](/en/guides/endpoints/#server-endpoints-api-routes).
-
-This low-level API gives you access to all font files downloaded by Astro for your project, along with their metadata. This means that you are responsible for filtering font files to find the specific file you need, and for resolving the file path to use based on the build output structure.
-
-:::note
-The current API has a [known limitation that requires you to manually load the font file](https://github.com/withastro/astro/issues/16139) from the output path at build time.
-
+To avoid this, Astro automatically tries to generate optimized fallback fonts from the last [defined fallback](/en/reference/configuration-reference/#fontfallbacks) if it is a [generic font family](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/font-family#generic-name). It uses `sans-serif` by default, but it may not match the desired appearance of your primary font. You can adjust it in your font configuration:
+
+```mjs title="astro.config.mjs" {8}
+import { defineConfig, fontProviders } from "astro/config";
+
+export default defineConfig({
+  fonts: [{
+    provider: fontProviders.fontsource(),
+    name: "Cousine",
+    cssVariable: "--font-cousine",
+    fallbacks: ["monospace"]
+  }]
+});
+```
+
+You can also opt out of the default optimization by setting [`font.optimizedFallbacks`](/en/reference/configuration-reference/#fontoptimizedfallbacks) to `false` in your font configuration. Astro will then use the fallback fonts specified in your configuration without any additional automatic processing.
+
+## Accessing font data programmatically
+
+Astro exposes a low-level API for accessing font family data programmatically through the [`fontData`](/en/reference/modules/astro-assets/#fontdata) object. This can be useful for advanced use cases where you need direct access to font files, such as generating OpenGraph images with [satori](https://github.com/vercel/satori) in an [API Route](/en/guides/endpoints/#server-endpoints-api-routes).
+
+This low-level API gives you access to all font files downloaded by Astro for your project, along with their metadata. This means that you are responsible for filtering font files to find the specific file you need, and for resolving the file path to use based on the build output structure.
+
+:::note
+The current API has a [known limitation that requires you to manually load the font file](https://github.com/withastro/astro/issues/16139) from the output path at build time.
+
 A new API is being developed to simplify this process and will be available in a future release. You can subscribe to the GitHub issue to follow its progress.
-:::
-
-The following example generates an OpenGraph image in a static file endpoint, assuming that only one font has been configured with a [format supported by Satori](https://github.com/vercel/satori?tab=readme-ov-file#fonts):
-
-```tsx title="src/pages/og.png.ts" {2} "fontData[\"--font-roboto\"]"
-import type { APIRoute } from "astro";
-import { fontData } from "astro:assets";
-import { outDir } from "astro:config/server";
-import { readFile } from "node:fs/promises";
-import satori from "satori";
-import { html } from "satori-html";
-import sharp from "sharp";
-
-export const GET: APIRoute = async (context) => {
-  const fontPath = fontData["--font-roboto"][0]?.src[0]?.url;
-
-  if (fontPath === undefined) {
-    throw new Error("Cannot find the font path.");
-  }
-
-  const data = import.meta.env.DEV
-    ? await fetch(new URL(fontPath, context.url.origin)).then(async (res) => res.arrayBuffer())
-    : await readFile(new URL(`.${fontPath}`, outDir));
-
-  const svg = await satori(
-    html`<div style="color: black;">hello, world</div>`,
-    {
-      width: 600,
-      height: 400,
-      fonts: [
-        {
-          name: "Roboto",
-          data,
-          weight: 400,
-          style: "normal",
-        },
-      ],
-    },
-  );
-
-  const pngBuffer = await sharp(Buffer.from(svg))
-    .resize(600, 400)
-    .png()
-    .toBuffer();
-
-  return new Response(new Uint8Array(pngBuffer), {
-    headers: {
-      "Content-Type": "image/png",
-    },
-  });
-};
-```
-
-## Granular font configuration
-
-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 title="astro.config.mjs"
-import { defineConfig, fontProviders } from "astro/config";
-
-export default defineConfig({
-  fonts: [
-    {
-      name: "Roboto",
-      cssVariable: "--roboto",
-      provider: fontProviders.google(),
-      weights: [500, 600],
-      styles: ["normal"]
-    },
-    {
-      name: "Roboto",
-      cssVariable: "--roboto",
-      provider: fontProviders.google(),
-      weights: [500],
-      styles: ["italic"]
-    }
-  ]
-});
-```
-
-## Caching
-
-The Fonts API caching implementation was designed to be practical in development and efficient in production. During builds, font files are copied to the `_astro/fonts` output directory, so they can benefit from HTTP caching of static assets (usually a year).
-
-To clear the cache in development, remove the `.astro/fonts` directory. To clear the build cache, remove the `node_modules/.astro/fonts` directory.
-
-## Examples
-
-Astro's font feature is based on flexible configuration options. Your own project's font configuration may look different from simplified examples, so the following are provided to show what various font configurations might look like when used in production.
-
-```js title="astro.config.mjs"
-import { defineConfig, fontProviders } from "astro/config";
-
-export default defineConfig({
-  fonts: [
-    {
-      name: "Roboto",
-      cssVariable: "--font-roboto",
-      provider: fontProviders.google(),
-      // Default included:
-      // weights: [400] ,
-      // styles: ["normal", "italic"],
-      // subsets: ["latin"],
-      // fallbacks: ["sans-serif"], 
-      // formats: ["woff2"],
-    },
-    {
-      name: "Inter",
-      cssVariable: "--font-inter",
-      provider: fontProviders.fontsource(),
-      // Specify weights that are actually used
-      weights: [400, 500, 600, 700],
-      // Specify styles that are actually used
-      styles: ["normal"],
-      // Download only font files for characters used on the page
-      subsets: ["latin", "cyrillic"],
-      // Download more font formats
-      formats: ["woff2", "woff"],
-    },
-    {
-      name: "JetBrains Mono",
-      cssVariable: "--font-jetbrains-mono",
-      provider: fontProviders.fontsource(),
-      // Download only font files for characters used on the page
-      subsets: ["latin", "latin-ext"],
-      // Use a fallback font family matching the intended appearance
-      fallbacks: ["monospace"],
-    },
-    {
-      name: "Poppins",
-      cssVariable: "--font-poppins",
-      provider: fontProviders.local(),
-      options: {
-        // Weight and style are not specified so Astro
-        // will try to infer them for each variant
-        variants: [
-          {
-            src: [
-              "./src/assets/fonts/Poppins-regular.woff2",
-              "./src/assets/fonts/Poppins-regular.woff",
-            ]
-          },
-          {
-            src: [
-              "./src/assets/fonts/Poppins-bold.woff2",
-              "./src/assets/fonts/Poppins-bold.woff",
-            ]
-          },
-        ]
-      }
-    }
-  ],
-});
-```
+:::
+
+The following example generates an OpenGraph image in a static file endpoint, assuming that only one font has been configured with a [format supported by Satori](https://github.com/vercel/satori?tab=readme-ov-file#fonts):
+
+```tsx title="src/pages/og.png.ts" {2} "fontData[\"--font-roboto\"]"
+import type { APIRoute } from "astro";
+import { fontData } from "astro:assets";
+import { outDir } from "astro:config/server";
+import { readFile } from "node:fs/promises";
+import satori from "satori";
+import { html } from "satori-html";
+import sharp from "sharp";
+
+export const GET: APIRoute = async (context) => {
+  const fontPath = fontData["--font-roboto"][0]?.src[0]?.url;
+
+  if (fontPath === undefined) {
+    throw new Error("Cannot find the font path.");
+  }
+
+  const data = import.meta.env.DEV
+    ? await fetch(new URL(fontPath, context.url.origin)).then(async (res) => res.arrayBuffer())
+    : await readFile(new URL(`.${fontPath}`, outDir));
+
+  const svg = await satori(
+    html`<div style="color: black;">hello, world</div>`,
+    {
+      width: 600,
+      height: 400,
+      fonts: [
+        {
+          name: "Roboto",
+          data,
+          weight: 400,
+          style: "normal",
+        },
+      ],
+    },
+  );
+
+  const pngBuffer = await sharp(Buffer.from(svg))
+    .resize(600, 400)
+    .png()
+    .toBuffer();
+
+  return new Response(new Uint8Array(pngBuffer), {
+    headers: {
+      "Content-Type": "image/png",
+    },
+  });
+};
+```
+
+## Granular font configuration
+
+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 title="astro.config.mjs"
+import { defineConfig, fontProviders } from "astro/config";
+
+export default defineConfig({
+  fonts: [
+    {
+      name: "Roboto",
+      cssVariable: "--roboto",
+      provider: fontProviders.google(),
+      weights: [500, 600],
+      styles: ["normal"]
+    },
+    {
+      name: "Roboto",
+      cssVariable: "--roboto",
+      provider: fontProviders.google(),
+      weights: [500],
+      styles: ["italic"]
+    }
+  ]
+});
+```
+
+## Caching
+
+The Fonts API caching implementation was designed to be practical in development and efficient in production. During builds, font files are copied to the `_astro/fonts` output directory, so they can benefit from HTTP caching of static assets (usually a year).
+
+To clear the cache in development, remove the `.astro/fonts` directory. To clear the build cache, remove the `node_modules/.astro/fonts` directory.
+
+## Examples
+
+Astro's font feature is based on flexible configuration options. Your own project's font configuration may look different from simplified examples, so the following are provided to show what various font configurations might look like when used in production.
+
+```js title="astro.config.mjs"
+import { defineConfig, fontProviders } from "astro/config";
+
+export default defineConfig({
+  fonts: [
+    {
+      name: "Roboto",
+      cssVariable: "--font-roboto",
+      provider: fontProviders.google(),
+      // Default included:
+      // weights: [400] ,
+      // styles: ["normal", "italic"],
+      // subsets: ["latin"],
+      // fallbacks: ["sans-serif"], 
+      // formats: ["woff2"],
+    },
+    {
+      name: "Inter",
+      cssVariable: "--font-inter",
+      provider: fontProviders.fontsource(),
+      // Specify weights that are actually used
+      weights: [400, 500, 600, 700],
+      // Specify styles that are actually used
+      styles: ["normal"],
+      // Download only font files for characters used on the page
+      subsets: ["latin", "cyrillic"],
+      // Download more font formats
+      formats: ["woff2", "woff"],
+    },
+    {
+      name: "JetBrains Mono",
+      cssVariable: "--font-jetbrains-mono",
+      provider: fontProviders.fontsource(),
+      // Download only font files for characters used on the page
+      subsets: ["latin", "latin-ext"],
+      // Use a fallback font family matching the intended appearance
+      fallbacks: ["monospace"],
+    },
+    {
+      name: "Poppins",
+      cssVariable: "--font-poppins",
+      provider: fontProviders.local(),
+      options: {
+        // Weight and style are not specified so Astro
+        // will try to infer them for each variant
+        variants: [
+          {
+            src: [
+              "./src/assets/fonts/Poppins-regular.woff2",
+              "./src/assets/fonts/Poppins-regular.woff",
+            ]
+          },
+          {
+            src: [
+              "./src/assets/fonts/Poppins-bold.woff2",
+              "./src/assets/fonts/Poppins-bold.woff",
+            ]
+          },
+        ]
+      }
+    }
+  ],
+});
+```

From 5b5e78836cb25880b4e54f3a09cac0217da30233 Mon Sep 17 00:00:00 2001
From: Armand Philippot <git@armand.philippot.eu>
Date: Tue, 7 Apr 2026 12:35:32 +0200
Subject: [PATCH 09/13] rename variable fonts tabs + small rewording

---
 src/content/docs/en/guides/fonts.mdx | 882 +++++++++++++--------------
 1 file changed, 441 insertions(+), 441 deletions(-)

diff --git a/src/content/docs/en/guides/fonts.mdx b/src/content/docs/en/guides/fonts.mdx
index e1aaf52b384c2..becc0388f6e74 100644
--- a/src/content/docs/en/guides/fonts.mdx
+++ b/src/content/docs/en/guides/fonts.mdx
@@ -1,441 +1,441 @@
----
-title: Using custom fonts
-sidebar:
-  label: Fonts
-description: >-
-  Looking to add some custom typefaces to an Astro website? Use Google Fonts
-  with Fontsource or add a font of your choice.
-i18nReady: true
----
-import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
-import ReadMore from '~/components/ReadMore.astro';
-import { Steps, Tabs, TabItem } from '@astrojs/starlight/components';
-
-This guide will show you how to add [web fonts](https://developer.mozilla.org/en-US/docs/Learn/CSS/Styling_text/Web_fonts) to your project and use them in your components.
-
-Astro provides a way to use fonts from your filesystem and various font providers (e.g. Fontsource, Google) through a unified, [fully customizable](/en/reference/configuration-reference/#fonts), and type-safe API.
-
-Web fonts can impact page performance at both load time and rendering time. This API helps you keep your site performant with automatic [web font optimizations](https://web.dev/learn/performance/optimize-web-fonts) including preload links, optimized fallbacks, and opinionated defaults. [See common usage examples](#examples).
-
-The Fonts API focuses on performance and privacy by downloading and caching fonts so they're served from your site. This can avoid sending user data to third-party sites, and also ensures that a consistent set of fonts is available to all your visitors.
-
-## Configuring custom fonts
-
-Registering custom fonts for your Astro project is done through [the `fonts` option](/en/reference/configuration-reference/#fonts) in your Astro config.
-
-For each font you want to use, you must specify its [name](/en/reference/configuration-reference/#fontname), a [CSS variable](/en/reference/configuration-reference/#fontcssvariable), and an Astro font provider.
-
-Astro provides [built-in support for the most popular font providers](/en/reference/font-provider-reference/#built-in-providers): Adobe, Bunny, Fontshare, Fontsource, Google, Google Icons and NPM, as well as for using your own local font files. Additionally, you can [further customize your font configuration](#granular-font-configuration) to optimize performance and visitor experience.
-
-
-### Using a local font file
-
-This example will demonstrate adding a custom font using the font file `DistantGalaxy.woff2`.
-
-<Steps>
-
-1. Add your font file inside the [`src/` directory](/en/basics/project-structure/#src), for example `src/assets/fonts/`.
-
-2. Create a new font family in your Astro config file using the [local font provider](/en/reference/font-provider-reference/#local) and specify the variants to be included:
-
-    ```js title="astro.config.mjs"
-    import { defineConfig, fontProviders } from "astro/config";
-
-    export default defineConfig({
-      fonts: [{
-        provider: fontProviders.local(),
-        name: "DistantGalaxy",
-        cssVariable: "--font-distant-galaxy",
-        options: {
-          variants: [{
-            src: ['./src/assets/fonts/DistantGalaxy.woff2'],
-            weight: 'normal',
-            style: 'normal'
-          }]
-        }
-      }]
-    });
-    ```
-3. Your font is now configured and ready to be [added to your page head](#applying-custom-fonts) so that it can be used in your project.
-
-</Steps>
-
-### Using Fontsource
-
-Astro supports [several font providers](/en/reference/font-provider-reference/#built-in-providers) out of the box, including support for [Fontsource](https://fontsource.org/) that simplifies using Google Fonts and other open-source fonts.
-
-The following example will use Fontsource to add custom font support, but the process is similar for any of Astro's built-in font providers (e.g. [Adobe](https://fonts.adobe.com/), [Bunny](https://fonts.bunny.net/)).
-
-<Steps>
-
-1. Find the font you want to use in [Fontsource's catalog](https://fontsource.org/). This example will use [Roboto](https://fontsource.org/fonts/roboto).
-
-2. Create a new font family in your Astro config file using the [Fontsource provider](/en/reference/font-provider-reference/#fontsource):
-
-    ```js title="astro.config.mjs"
-    import { defineConfig, fontProviders } from "astro/config";
-
-    export default defineConfig({
-      fonts: [{
-        provider: fontProviders.fontsource(),
-        name: "Roboto",
-        cssVariable: "--font-roboto",
-      }]
-    });
-    ```
-3. Your font is now configured and ready to be [added to your page head](#applying-custom-fonts) so that it can be used in your project.
-
-</Steps>
-
-## Applying custom fonts
-
-After [a font is configured](#configuring-custom-fonts), it must be added to your page head with an identifying CSS variable. Then, you can use this variable when defining your page styles.
-
-<Steps>
-
-1. Import and include the [`<Font />`](/en/reference/modules/astro-assets/#font-) component with the required `cssVariable` property in the head of your page, usually in a dedicated `Head.astro` component or in a [layout](/en/basics/layouts/) component directly:
-
-    ```astro title="src/layouts/Layout.astro" ins={2,7}
-    ---
-    import { Font } from "astro:assets";
-    ---
-
-    <html>
-      <head>
-        <Font cssVariable="--font-distant-galaxy" />
-      </head>
-      <body>
-        <slot />
-      </body>
-    </html>
-    ```
-
-2. In any page rendered with that layout, including the layout component itself, you can now define styles with your font's `cssVariable` to apply your custom font.
-
-    In the following example, the `<h1>` heading will have the custom font applied, while the paragraph `<p>` will not.
-
-    ```astro title="src/pages/example.astro" ins={10-12}
-    ---
-    import Layout from "../layouts/Layout.astro";
-    ---
-    <Layout>
-      <h1>In a galaxy far, far away...</h1>
-
-      <p>Custom fonts make my headings much cooler!</p>
-
-      <style>
-      h1 {
-        font-family: var(--font-distant-galaxy);
-      }
-      </style>
-    </Layout>
-    ```
-
-</Steps>
-
-### Preloading fonts
-
-Font preloading should be done sparingly, as it can block the loading of other important resources or download fonts unnecessary for the current page. Consider preloading only the most essential fonts, necessary for displaying content visible above the fold.
-
-To preload a font, pass the [`preload` property](/en/reference/modules/astro-assets/#preload) to the corresponding `<Font />` component. If multiple files correspond to a font, you can also specify which one to preload by passing an array.
-
-```astro title="src/layouts/Layout.astro" {7}
----
-import { Font } from "astro:assets";
----
-
-<html>
-  <head>
-    <Font cssVariable="--font-distant-galaxy" preload />
-  </head>
-  <body>
-    <slot />
-  </body>
-</html>
-```
-
-## Register fonts in Tailwind
-
-If you are using [Tailwind](/en/guides/styling/#tailwind) for styling, you will not apply your styles with the `font-face` CSS property.
-
-Instead, after [configuring your custom font](#configuring-custom-fonts) and [adding it to your page head](#applying-custom-fonts), you will need to update your Tailwind configuration to register your font:
-
-    <Tabs>
-
-    <TabItem label="Tailwind CSS 4.0">
-
-    ```css title="src/styles/global.css" ins={4} ins="inline"
-    @import "tailwindcss";
-
-    @theme inline {
-      --font-sans: var(--font-roboto);
-    }
-    ```
-
-    </TabItem>
-
-    <TabItem label="Tailwind CSS 3.0">
-
-    ```js title="tailwind.config.mjs" ins={6-8}
-    /** @type {import("tailwindcss").Config} */
-    export default {
-      content: ["./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}"],
-      theme: {
-        extend: {},
-        fontFamily: {
-          sans: ["var(--font-roboto)"]
-        }
-      },
-      plugins: []
-    };
-    ```
-
-    </TabItem>
-
-    </Tabs>
-
-See [Tailwind's docs on adding custom font families](https://tailwindcss.com/docs/font-family#using-a-custom-value) for more information.
-
-## Using variable fonts
-
-To use [variable fonts](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_fonts/Variable_fonts_guide) in your project, you can specify the range of available weights for the font instead of individual weights in your provider's configuration.
-
-<Tabs>
-<TabItem label="With a provider">
-
-When [using a font provider](#using-fontsource) that supports variable fonts, you can specify that the variable version of a font should be downloaded by setting the [`weights` property](/en/reference/configuration-reference/#fontweights) with an array containing the exact range of weights available for the font.
-
-The following example downloads [Fira Code from Fontsource](https://fontsource.org/fonts/fira-code) as a variable font with the available weight range:
-
-```js title="astro.config.mjs" {9}
-import { defineConfig, fontProviders } from "astro/config";
-
-export default defineConfig({
-  fonts: [{
-    cssVariable: "--font-fira-code",
-    name: "Fira Code",
-    provider: fontProviders.fontsource(),
-    styles: ["normal"],
-    weights: ["300 700"],
-  }]
-});
-```
-
-</TabItem>
-<TabItem label="With a local font file">
-
-When [using a local font file](#using-a-local-font-file), you can specify that the font is variable by setting the [`weight` property of the variant](/en/reference/font-provider-reference/#weight) to a string corresponding to the exact weight range available for the font.
-
-The following example configures Inter as a local variable font with the available weight range:
-
-```js title="astro.config.mjs" {11}
-import { defineConfig, fontProviders } from "astro/config";
-
-export default defineConfig({
-  fonts: [{
-    provider: fontProviders.local(),
-    name: "Inter",
-    cssVariable: "--font-inter",
-    options: {
-      variants: [
-        {
-          weight: "100 900",
-          style: "normal",
-          src: ["./src/assets/fonts/InterVariable.woff2"],
-        },
-      ],
-    },
-  }]
-});
-```
-
-</TabItem>
-</Tabs>
-
-## Customizing font fallbacks
-
-Fallback fonts are used when the primary font has not yet loaded, contains missing characters, or cannot be loaded for any reason. When the fallback font differs significantly from the primary font, layout shifts may occur during page loading. 
-
-To avoid this, Astro automatically tries to generate optimized fallback fonts from the last [defined fallback](/en/reference/configuration-reference/#fontfallbacks) if it is a [generic font family](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/font-family#generic-name). It uses `sans-serif` by default, but it may not match the desired appearance of your primary font. You can adjust it in your font configuration:
-
-```mjs title="astro.config.mjs" {8}
-import { defineConfig, fontProviders } from "astro/config";
-
-export default defineConfig({
-  fonts: [{
-    provider: fontProviders.fontsource(),
-    name: "Cousine",
-    cssVariable: "--font-cousine",
-    fallbacks: ["monospace"]
-  }]
-});
-```
-
-You can also opt out of the default optimization by setting [`font.optimizedFallbacks`](/en/reference/configuration-reference/#fontoptimizedfallbacks) to `false` in your font configuration. Astro will then use the fallback fonts specified in your configuration without any additional automatic processing.
-
-## Accessing font data programmatically
-
-Astro exposes a low-level API for accessing font family data programmatically through the [`fontData`](/en/reference/modules/astro-assets/#fontdata) object. This can be useful for advanced use cases where you need direct access to font files, such as generating OpenGraph images with [satori](https://github.com/vercel/satori) in an [API Route](/en/guides/endpoints/#server-endpoints-api-routes).
-
-This low-level API gives you access to all font files downloaded by Astro for your project, along with their metadata. This means that you are responsible for filtering font files to find the specific file you need, and for resolving the file path to use based on the build output structure.
-
-:::note
-The current API has a [known limitation that requires you to manually load the font file](https://github.com/withastro/astro/issues/16139) from the output path at build time.
-
-A new API is being developed to simplify this process and will be available in a future release. You can subscribe to the GitHub issue to follow its progress.
-:::
-
-The following example generates an OpenGraph image in a static file endpoint, assuming that only one font has been configured with a [format supported by Satori](https://github.com/vercel/satori?tab=readme-ov-file#fonts):
-
-```tsx title="src/pages/og.png.ts" {2} "fontData[\"--font-roboto\"]"
-import type { APIRoute } from "astro";
-import { fontData } from "astro:assets";
-import { outDir } from "astro:config/server";
-import { readFile } from "node:fs/promises";
-import satori from "satori";
-import { html } from "satori-html";
-import sharp from "sharp";
-
-export const GET: APIRoute = async (context) => {
-  const fontPath = fontData["--font-roboto"][0]?.src[0]?.url;
-
-  if (fontPath === undefined) {
-    throw new Error("Cannot find the font path.");
-  }
-
-  const data = import.meta.env.DEV
-    ? await fetch(new URL(fontPath, context.url.origin)).then(async (res) => res.arrayBuffer())
-    : await readFile(new URL(`.${fontPath}`, outDir));
-
-  const svg = await satori(
-    html`<div style="color: black;">hello, world</div>`,
-    {
-      width: 600,
-      height: 400,
-      fonts: [
-        {
-          name: "Roboto",
-          data,
-          weight: 400,
-          style: "normal",
-        },
-      ],
-    },
-  );
-
-  const pngBuffer = await sharp(Buffer.from(svg))
-    .resize(600, 400)
-    .png()
-    .toBuffer();
-
-  return new Response(new Uint8Array(pngBuffer), {
-    headers: {
-      "Content-Type": "image/png",
-    },
-  });
-};
-```
-
-## Granular font configuration
-
-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 title="astro.config.mjs"
-import { defineConfig, fontProviders } from "astro/config";
-
-export default defineConfig({
-  fonts: [
-    {
-      name: "Roboto",
-      cssVariable: "--roboto",
-      provider: fontProviders.google(),
-      weights: [500, 600],
-      styles: ["normal"]
-    },
-    {
-      name: "Roboto",
-      cssVariable: "--roboto",
-      provider: fontProviders.google(),
-      weights: [500],
-      styles: ["italic"]
-    }
-  ]
-});
-```
-
-## Caching
-
-The Fonts API caching implementation was designed to be practical in development and efficient in production. During builds, font files are copied to the `_astro/fonts` output directory, so they can benefit from HTTP caching of static assets (usually a year).
-
-To clear the cache in development, remove the `.astro/fonts` directory. To clear the build cache, remove the `node_modules/.astro/fonts` directory.
-
-## Examples
-
-Astro's font feature is based on flexible configuration options. Your own project's font configuration may look different from simplified examples, so the following are provided to show what various font configurations might look like when used in production.
-
-```js title="astro.config.mjs"
-import { defineConfig, fontProviders } from "astro/config";
-
-export default defineConfig({
-  fonts: [
-    {
-      name: "Roboto",
-      cssVariable: "--font-roboto",
-      provider: fontProviders.google(),
-      // Default included:
-      // weights: [400] ,
-      // styles: ["normal", "italic"],
-      // subsets: ["latin"],
-      // fallbacks: ["sans-serif"], 
-      // formats: ["woff2"],
-    },
-    {
-      name: "Inter",
-      cssVariable: "--font-inter",
-      provider: fontProviders.fontsource(),
-      // Specify weights that are actually used
-      weights: [400, 500, 600, 700],
-      // Specify styles that are actually used
-      styles: ["normal"],
-      // Download only font files for characters used on the page
-      subsets: ["latin", "cyrillic"],
-      // Download more font formats
-      formats: ["woff2", "woff"],
-    },
-    {
-      name: "JetBrains Mono",
-      cssVariable: "--font-jetbrains-mono",
-      provider: fontProviders.fontsource(),
-      // Download only font files for characters used on the page
-      subsets: ["latin", "latin-ext"],
-      // Use a fallback font family matching the intended appearance
-      fallbacks: ["monospace"],
-    },
-    {
-      name: "Poppins",
-      cssVariable: "--font-poppins",
-      provider: fontProviders.local(),
-      options: {
-        // Weight and style are not specified so Astro
-        // will try to infer them for each variant
-        variants: [
-          {
-            src: [
-              "./src/assets/fonts/Poppins-regular.woff2",
-              "./src/assets/fonts/Poppins-regular.woff",
-            ]
-          },
-          {
-            src: [
-              "./src/assets/fonts/Poppins-bold.woff2",
-              "./src/assets/fonts/Poppins-bold.woff",
-            ]
-          },
-        ]
-      }
-    }
-  ],
-});
-```
+---
+title: Using custom fonts
+sidebar:
+  label: Fonts
+description: >-
+  Looking to add some custom typefaces to an Astro website? Use Google Fonts
+  with Fontsource or add a font of your choice.
+i18nReady: true
+---
+import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
+import ReadMore from '~/components/ReadMore.astro';
+import { Steps, Tabs, TabItem } from '@astrojs/starlight/components';
+
+This guide will show you how to add [web fonts](https://developer.mozilla.org/en-US/docs/Learn/CSS/Styling_text/Web_fonts) to your project and use them in your components.
+
+Astro provides a way to use fonts from your filesystem and various font providers (e.g. Fontsource, Google) through a unified, [fully customizable](/en/reference/configuration-reference/#fonts), and type-safe API.
+
+Web fonts can impact page performance at both load time and rendering time. This API helps you keep your site performant with automatic [web font optimizations](https://web.dev/learn/performance/optimize-web-fonts) including preload links, optimized fallbacks, and opinionated defaults. [See common usage examples](#examples).
+
+The Fonts API focuses on performance and privacy by downloading and caching fonts so they're served from your site. This can avoid sending user data to third-party sites, and also ensures that a consistent set of fonts is available to all your visitors.
+
+## Configuring custom fonts
+
+Registering custom fonts for your Astro project is done through [the `fonts` option](/en/reference/configuration-reference/#fonts) in your Astro config.
+
+For each font you want to use, you must specify its [name](/en/reference/configuration-reference/#fontname), a [CSS variable](/en/reference/configuration-reference/#fontcssvariable), and an Astro font provider.
+
+Astro provides [built-in support for the most popular font providers](/en/reference/font-provider-reference/#built-in-providers): Adobe, Bunny, Fontshare, Fontsource, Google, Google Icons and NPM, as well as for using your own local font files. Additionally, you can [further customize your font configuration](#granular-font-configuration) to optimize performance and visitor experience.
+
+
+### Using a local font file
+
+This example will demonstrate adding a custom font using the font file `DistantGalaxy.woff2`.
+
+<Steps>
+
+1. Add your font file inside the [`src/` directory](/en/basics/project-structure/#src), for example `src/assets/fonts/`.
+
+2. Create a new font family in your Astro config file using the [local font provider](/en/reference/font-provider-reference/#local) and specify the variants to be included:
+
+    ```js title="astro.config.mjs"
+    import { defineConfig, fontProviders } from "astro/config";
+
+    export default defineConfig({
+      fonts: [{
+        provider: fontProviders.local(),
+        name: "DistantGalaxy",
+        cssVariable: "--font-distant-galaxy",
+        options: {
+          variants: [{
+            src: ['./src/assets/fonts/DistantGalaxy.woff2'],
+            weight: 'normal',
+            style: 'normal'
+          }]
+        }
+      }]
+    });
+    ```
+3. Your font is now configured and ready to be [added to your page head](#applying-custom-fonts) so that it can be used in your project.
+
+</Steps>
+
+### Using Fontsource
+
+Astro supports [several font providers](/en/reference/font-provider-reference/#built-in-providers) out of the box, including support for [Fontsource](https://fontsource.org/) that simplifies using Google Fonts and other open-source fonts.
+
+The following example will use Fontsource to add custom font support, but the process is similar for any of Astro's built-in font providers (e.g. [Adobe](https://fonts.adobe.com/), [Bunny](https://fonts.bunny.net/)).
+
+<Steps>
+
+1. Find the font you want to use in [Fontsource's catalog](https://fontsource.org/). This example will use [Roboto](https://fontsource.org/fonts/roboto).
+
+2. Create a new font family in your Astro config file using the [Fontsource provider](/en/reference/font-provider-reference/#fontsource):
+
+    ```js title="astro.config.mjs"
+    import { defineConfig, fontProviders } from "astro/config";
+
+    export default defineConfig({
+      fonts: [{
+        provider: fontProviders.fontsource(),
+        name: "Roboto",
+        cssVariable: "--font-roboto",
+      }]
+    });
+    ```
+3. Your font is now configured and ready to be [added to your page head](#applying-custom-fonts) so that it can be used in your project.
+
+</Steps>
+
+## Applying custom fonts
+
+After [a font is configured](#configuring-custom-fonts), it must be added to your page head with an identifying CSS variable. Then, you can use this variable when defining your page styles.
+
+<Steps>
+
+1. Import and include the [`<Font />`](/en/reference/modules/astro-assets/#font-) component with the required `cssVariable` property in the head of your page, usually in a dedicated `Head.astro` component or in a [layout](/en/basics/layouts/) component directly:
+
+    ```astro title="src/layouts/Layout.astro" ins={2,7}
+    ---
+    import { Font } from "astro:assets";
+    ---
+
+    <html>
+      <head>
+        <Font cssVariable="--font-distant-galaxy" />
+      </head>
+      <body>
+        <slot />
+      </body>
+    </html>
+    ```
+
+2. In any page rendered with that layout, including the layout component itself, you can now define styles with your font's `cssVariable` to apply your custom font.
+
+    In the following example, the `<h1>` heading will have the custom font applied, while the paragraph `<p>` will not.
+
+    ```astro title="src/pages/example.astro" ins={10-12}
+    ---
+    import Layout from "../layouts/Layout.astro";
+    ---
+    <Layout>
+      <h1>In a galaxy far, far away...</h1>
+
+      <p>Custom fonts make my headings much cooler!</p>
+
+      <style>
+      h1 {
+        font-family: var(--font-distant-galaxy);
+      }
+      </style>
+    </Layout>
+    ```
+
+</Steps>
+
+### Preloading fonts
+
+Font preloading should be done sparingly, as it can block the loading of other important resources or download fonts unnecessary for the current page. Consider preloading only the most essential fonts, necessary for displaying content visible above the fold.
+
+To preload a font, pass the [`preload` property](/en/reference/modules/astro-assets/#preload) to the corresponding `<Font />` component. If multiple files correspond to a font, you can also specify which one to preload by passing an array.
+
+```astro title="src/layouts/Layout.astro" {7}
+---
+import { Font } from "astro:assets";
+---
+
+<html>
+  <head>
+    <Font cssVariable="--font-distant-galaxy" preload />
+  </head>
+  <body>
+    <slot />
+  </body>
+</html>
+```
+
+## Register fonts in Tailwind
+
+If you are using [Tailwind](/en/guides/styling/#tailwind) for styling, you will not apply your styles with the `font-face` CSS property.
+
+Instead, after [configuring your custom font](#configuring-custom-fonts) and [adding it to your page head](#applying-custom-fonts), you will need to update your Tailwind configuration to register your font:
+
+    <Tabs>
+
+    <TabItem label="Tailwind CSS 4.0">
+
+    ```css title="src/styles/global.css" ins={4} ins="inline"
+    @import "tailwindcss";
+
+    @theme inline {
+      --font-sans: var(--font-roboto);
+    }
+    ```
+
+    </TabItem>
+
+    <TabItem label="Tailwind CSS 3.0">
+
+    ```js title="tailwind.config.mjs" ins={6-8}
+    /** @type {import("tailwindcss").Config} */
+    export default {
+      content: ["./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}"],
+      theme: {
+        extend: {},
+        fontFamily: {
+          sans: ["var(--font-roboto)"]
+        }
+      },
+      plugins: []
+    };
+    ```
+
+    </TabItem>
+
+    </Tabs>
+
+See [Tailwind's docs on adding custom font families](https://tailwindcss.com/docs/font-family#using-a-custom-value) for more information.
+
+## Using variable fonts
+
+To use [variable fonts](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_fonts/Variable_fonts_guide) in your project, specify the available weight range instead of individual weights in your provider's configuration.
+
+<Tabs>
+<TabItem label="Local provider">
+
+When [using a local font file](#using-a-local-font-file), you can specify that the font is variable by setting the [`weight` property of the variant](/en/reference/font-provider-reference/#weight) to a string corresponding to the exact weight range available for the font.
+
+The following example configures Inter as a local variable font with the available weight range:
+
+```js title="astro.config.mjs" {11}
+import { defineConfig, fontProviders } from "astro/config";
+
+export default defineConfig({
+  fonts: [{
+    provider: fontProviders.local(),
+    name: "Inter",
+    cssVariable: "--font-inter",
+    options: {
+      variants: [
+        {
+          weight: "100 900",
+          style: "normal",
+          src: ["./src/assets/fonts/InterVariable.woff2"],
+        },
+      ],
+    },
+  }]
+});
+```
+
+</TabItem>
+<TabItem label="Other providers">
+
+When using [other providers (e.g. Fontsource)](#using-fontsource), that support variable fonts, you can request the variable version of a font by setting the [`weights` property](/en/reference/configuration-reference/#fontweights) with an array containing the exact range of weights available for the font.
+
+The following example downloads [Fira Code from Fontsource](https://fontsource.org/fonts/fira-code) as a variable font with the available weight range:
+
+```js title="astro.config.mjs" {9}
+import { defineConfig, fontProviders } from "astro/config";
+
+export default defineConfig({
+  fonts: [{
+    cssVariable: "--font-fira-code",
+    name: "Fira Code",
+    provider: fontProviders.fontsource(),
+    styles: ["normal"],
+    weights: ["300 700"],
+  }]
+});
+```
+
+</TabItem>
+</Tabs>
+
+## Customizing font fallbacks
+
+Fallback fonts are used when the primary font has not yet loaded, contains missing characters, or cannot be loaded for any reason. When the fallback font differs significantly from the primary font, layout shifts may occur during page loading. 
+
+To avoid this, Astro automatically tries to generate optimized fallback fonts from the last [defined fallback](/en/reference/configuration-reference/#fontfallbacks) if it is a [generic font family](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/font-family#generic-name). It uses `sans-serif` by default, but it may not match the desired appearance of your primary font. You can adjust it in your font configuration:
+
+```mjs title="astro.config.mjs" {8}
+import { defineConfig, fontProviders } from "astro/config";
+
+export default defineConfig({
+  fonts: [{
+    provider: fontProviders.fontsource(),
+    name: "Cousine",
+    cssVariable: "--font-cousine",
+    fallbacks: ["monospace"]
+  }]
+});
+```
+
+You can also opt out of the default optimization by setting [`font.optimizedFallbacks`](/en/reference/configuration-reference/#fontoptimizedfallbacks) to `false` in your font configuration. Astro will then use the fallback fonts specified in your configuration without any additional automatic processing.
+
+## Accessing font data programmatically
+
+Astro exposes a low-level API for accessing font family data programmatically through the [`fontData`](/en/reference/modules/astro-assets/#fontdata) object. This can be useful for advanced use cases where you need direct access to font files, such as generating OpenGraph images with [satori](https://github.com/vercel/satori) in an [API Route](/en/guides/endpoints/#server-endpoints-api-routes).
+
+This low-level API gives you access to all font files downloaded by Astro for your project, along with their metadata. This means that you are responsible for filtering font files to find the specific file you need, and for resolving the file path to use based on the build output structure.
+
+:::note
+The current API has a [known limitation that requires you to manually load the font file](https://github.com/withastro/astro/issues/16139) from the output path at build time.
+
+A new API is being developed to simplify this process and will be available in a future release. You can subscribe to the GitHub issue to follow its progress.
+:::
+
+The following example generates an OpenGraph image in a static file endpoint, assuming that only one font has been configured with a [format supported by Satori](https://github.com/vercel/satori?tab=readme-ov-file#fonts):
+
+```tsx title="src/pages/og.png.ts" {2} "fontData[\"--font-roboto\"]"
+import type { APIRoute } from "astro";
+import { fontData } from "astro:assets";
+import { outDir } from "astro:config/server";
+import { readFile } from "node:fs/promises";
+import satori from "satori";
+import { html } from "satori-html";
+import sharp from "sharp";
+
+export const GET: APIRoute = async (context) => {
+  const fontPath = fontData["--font-roboto"][0]?.src[0]?.url;
+
+  if (fontPath === undefined) {
+    throw new Error("Cannot find the font path.");
+  }
+
+  const data = import.meta.env.DEV
+    ? await fetch(new URL(fontPath, context.url.origin)).then(async (res) => res.arrayBuffer())
+    : await readFile(new URL(`.${fontPath}`, outDir));
+
+  const svg = await satori(
+    html`<div style="color: black;">hello, world</div>`,
+    {
+      width: 600,
+      height: 400,
+      fonts: [
+        {
+          name: "Roboto",
+          data,
+          weight: 400,
+          style: "normal",
+        },
+      ],
+    },
+  );
+
+  const pngBuffer = await sharp(Buffer.from(svg))
+    .resize(600, 400)
+    .png()
+    .toBuffer();
+
+  return new Response(new Uint8Array(pngBuffer), {
+    headers: {
+      "Content-Type": "image/png",
+    },
+  });
+};
+```
+
+## Granular font configuration
+
+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 title="astro.config.mjs"
+import { defineConfig, fontProviders } from "astro/config";
+
+export default defineConfig({
+  fonts: [
+    {
+      name: "Roboto",
+      cssVariable: "--roboto",
+      provider: fontProviders.google(),
+      weights: [500, 600],
+      styles: ["normal"]
+    },
+    {
+      name: "Roboto",
+      cssVariable: "--roboto",
+      provider: fontProviders.google(),
+      weights: [500],
+      styles: ["italic"]
+    }
+  ]
+});
+```
+
+## Caching
+
+The Fonts API caching implementation was designed to be practical in development and efficient in production. During builds, font files are copied to the `_astro/fonts` output directory, so they can benefit from HTTP caching of static assets (usually a year).
+
+To clear the cache in development, remove the `.astro/fonts` directory. To clear the build cache, remove the `node_modules/.astro/fonts` directory.
+
+## Examples
+
+Astro's font feature is based on flexible configuration options. Your own project's font configuration may look different from simplified examples, so the following are provided to show what various font configurations might look like when used in production.
+
+```js title="astro.config.mjs"
+import { defineConfig, fontProviders } from "astro/config";
+
+export default defineConfig({
+  fonts: [
+    {
+      name: "Roboto",
+      cssVariable: "--font-roboto",
+      provider: fontProviders.google(),
+      // Default included:
+      // weights: [400] ,
+      // styles: ["normal", "italic"],
+      // subsets: ["latin"],
+      // fallbacks: ["sans-serif"], 
+      // formats: ["woff2"],
+    },
+    {
+      name: "Inter",
+      cssVariable: "--font-inter",
+      provider: fontProviders.fontsource(),
+      // Specify weights that are actually used
+      weights: [400, 500, 600, 700],
+      // Specify styles that are actually used
+      styles: ["normal"],
+      // Download only font files for characters used on the page
+      subsets: ["latin", "cyrillic"],
+      // Download more font formats
+      formats: ["woff2", "woff"],
+    },
+    {
+      name: "JetBrains Mono",
+      cssVariable: "--font-jetbrains-mono",
+      provider: fontProviders.fontsource(),
+      // Download only font files for characters used on the page
+      subsets: ["latin", "latin-ext"],
+      // Use a fallback font family matching the intended appearance
+      fallbacks: ["monospace"],
+    },
+    {
+      name: "Poppins",
+      cssVariable: "--font-poppins",
+      provider: fontProviders.local(),
+      options: {
+        // Weight and style are not specified so Astro
+        // will try to infer them for each variant
+        variants: [
+          {
+            src: [
+              "./src/assets/fonts/Poppins-regular.woff2",
+              "./src/assets/fonts/Poppins-regular.woff",
+            ]
+          },
+          {
+            src: [
+              "./src/assets/fonts/Poppins-bold.woff2",
+              "./src/assets/fonts/Poppins-bold.woff",
+            ]
+          },
+        ]
+      }
+    }
+  ],
+});
+```

From c2c53b7e4a7f2451362e17964e5508fbd846d90b Mon Sep 17 00:00:00 2001
From: Armand Philippot <git@armand.philippot.eu>
Date: Tue, 7 Apr 2026 12:36:25 +0200
Subject: [PATCH 10/13] reword the satori code snippet introduction and add a
 new link

---
 src/content/docs/en/guides/fonts.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/content/docs/en/guides/fonts.mdx b/src/content/docs/en/guides/fonts.mdx
index becc0388f6e74..c2e85d25481b3 100644
--- a/src/content/docs/en/guides/fonts.mdx
+++ b/src/content/docs/en/guides/fonts.mdx
@@ -285,7 +285,7 @@ The current API has a [known limitation that requires you to manually load the f
 A new API is being developed to simplify this process and will be available in a future release. You can subscribe to the GitHub issue to follow its progress.
 :::
 
-The following example generates an OpenGraph image in a static file endpoint, assuming that only one font has been configured with a [format supported by Satori](https://github.com/vercel/satori?tab=readme-ov-file#fonts):
+The following example generates an OpenGraph image in a static file endpoint, assuming that only [one font and its format have been configured](/en/reference/configuration-reference/#fontformats) with a [format supported by Satori](https://github.com/vercel/satori?tab=readme-ov-file#fonts):
 
 ```tsx title="src/pages/og.png.ts" {2} "fontData[\"--font-roboto\"]"
 import type { APIRoute } from "astro";

From 8c29de7c0a79bcbf08e39f518241dcc11bde9ecf Mon Sep 17 00:00:00 2001
From: Armand Philippot <git@armand.philippot.eu>
Date: Tue, 7 Apr 2026 12:38:25 +0200
Subject: [PATCH 11/13] maybe preloading fonts should be an h2

---
 src/content/docs/en/guides/fonts.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/content/docs/en/guides/fonts.mdx b/src/content/docs/en/guides/fonts.mdx
index c2e85d25481b3..7f8663b00b0f5 100644
--- a/src/content/docs/en/guides/fonts.mdx
+++ b/src/content/docs/en/guides/fonts.mdx
@@ -133,7 +133,7 @@ After [a font is configured](#configuring-custom-fonts), it must be added to you
 
 </Steps>
 
-### Preloading fonts
+## Preloading fonts
 
 Font preloading should be done sparingly, as it can block the loading of other important resources or download fonts unnecessary for the current page. Consider preloading only the most essential fonts, necessary for displaying content visible above the fold.
 

From 47a4e9592d57fa197671b40acf99bd5f12189885 Mon Sep 17 00:00:00 2001
From: Armand Philippot <git@armand.philippot.eu>
Date: Tue, 7 Apr 2026 15:04:36 +0200
Subject: [PATCH 12/13] capital letter

Co-authored-by: Florian Lefebvre <contact@florian-lefebvre.dev>
---
 src/content/docs/en/guides/fonts.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/content/docs/en/guides/fonts.mdx b/src/content/docs/en/guides/fonts.mdx
index 7f8663b00b0f5..04f9c94752033 100644
--- a/src/content/docs/en/guides/fonts.mdx
+++ b/src/content/docs/en/guides/fonts.mdx
@@ -275,7 +275,7 @@ You can also opt out of the default optimization by setting [`font.optimizedFall
 
 ## Accessing font data programmatically
 
-Astro exposes a low-level API for accessing font family data programmatically through the [`fontData`](/en/reference/modules/astro-assets/#fontdata) object. This can be useful for advanced use cases where you need direct access to font files, such as generating OpenGraph images with [satori](https://github.com/vercel/satori) in an [API Route](/en/guides/endpoints/#server-endpoints-api-routes).
+Astro exposes a low-level API for accessing font family data programmatically through the [`fontData`](/en/reference/modules/astro-assets/#fontdata) object. This can be useful for advanced use cases where you need direct access to font files, such as generating OpenGraph images with [Satori](https://github.com/vercel/satori) in an [API Route](/en/guides/endpoints/#server-endpoints-api-routes).
 
 This low-level API gives you access to all font files downloaded by Astro for your project, along with their metadata. This means that you are responsible for filtering font files to find the specific file you need, and for resolving the file path to use based on the build output structure.
 

From 81fee3ecdef48111c80d120b1916d1490a2bd1e0 Mon Sep 17 00:00:00 2001
From: Armand Philippot <git@armand.philippot.eu>
Date: Tue, 7 Apr 2026 18:08:14 +0200
Subject: [PATCH 13/13] final fix!

Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com>
---
 src/content/docs/en/guides/fonts.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/content/docs/en/guides/fonts.mdx b/src/content/docs/en/guides/fonts.mdx
index 04f9c94752033..a9da7a2b776a1 100644
--- a/src/content/docs/en/guides/fonts.mdx
+++ b/src/content/docs/en/guides/fonts.mdx
@@ -135,7 +135,7 @@ After [a font is configured](#configuring-custom-fonts), it must be added to you
 
 ## Preloading fonts
 
-Font preloading should be done sparingly, as it can block the loading of other important resources or download fonts unnecessary for the current page. Consider preloading only the most essential fonts, necessary for displaying content visible above the fold.
+Font preloading should be done sparingly, as it can block the loading of other important resources or download fonts that are unnecessary for the current page. Consider preloading only the most essential fonts, necessary for displaying content visible above the fold.
 
 To preload a font, pass the [`preload` property](/en/reference/modules/astro-assets/#preload) to the corresponding `<Font />` component. If multiple files correspond to a font, you can also specify which one to preload by passing an array.