docs(website): add preload guide (#963)

* docs: add preload guide * perf(website): preload site fonts * docs: formatting and style * docs: add url link to open sans install page
fontsource · Apr 16, 2024 · 8d77a7f · 8d77a7f
1 parent db13200
commit 8d77a7f
Show file tree

Hide file tree

Showing 4 changed files with 94 additions and 0 deletions.
diff --git a/website/app/root.tsx b/website/app/root.tsx
@@ -46,6 +46,8 @@ import '@mantine/core/styles/Text.css';
 import '@mantine/core/styles/Title.css';
 import '@/styles/global.css';
 
+import interLatinURL from '@fontsource-variable/inter/files/inter-latin-wght-normal.woff2?url';
+import sourceCodeProLatinURL from '@fontsource-variable/source-code-pro/files/source-code-pro-latin-wght-normal.woff2?url';
 import { ColorSchemeScript, MantineProvider } from '@mantine/core';
 import type {
 	HeadersFunction,
@@ -77,6 +79,20 @@ export const links: LinksFunction = () => [
 		rel: 'preconnect',
 		href: 'https://cdn.jsdelivr.net/',
 	},
+	{
+		rel: 'preload',
+		as: 'font',
+		type: 'font/woff2',
+		crossOrigin: 'anonymous',
+		href: interLatinURL,
+	},
+	{
+		rel: 'preload',
+		as: 'font',
+		type: 'font/woff2',
+		crossOrigin: 'anonymous',
+		href: sourceCodeProLatinURL,
+	},
 	{
 		rel: 'apple-touch-icon',
 		sizes: '180x180',

diff --git a/website/docs/getting-started/display.mdx b/website/docs/getting-started/display.mdx
@@ -0,0 +1,39 @@
+---
+title: Font Display
+section: Contents
+---
+
+## Font Display
+
+---
+
+Font display is a CSS property that controls how fonts appear on your website. By default, Fontsource uses the `swap` value for the `font-display` property. This means that while a custom font is loading, the browser displays a fallback font. Once the custom font is ready, the browser swaps it in place of the fallback font.
+
+> **Note:** You can learn more about the `font-display` property in the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display).
+
+To customise the `font-display` property for a specific font, you can use the **Advanced** tab on each **[Install](https://fontsource.org/fonts/open-sans/install)** page to generate custom `@font-face` rules with your preferred value.
+
+<br />
+
+For example, to set the `font-display` property to `optional` for Open Sans. You can create the following `@font-face` rule:
+
+```css
+@font-face {
+  font-family: 'Open Sans Variable';
+  font-style: normal;
+  font-display: optional;
+  font-weight: 300 800;
+  src: url(@fontsource-variable/open-sans/files/open-sans-latin-wght-normal.woff2) format('woff2-variations');
+  unicode-range: U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0304,U+0308,U+0329,U+2000-206F,U+2074,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD;
+}
+```
+
+> **Note:**  This method is only compatible with **Vite-based** frameworks or similar setups that support CSS bundling with `url()` rewrites.
+
+You can then include this rule in your global CSS file and apply it to your components using the following CSS:
+
+```css
+body {
+  font-family: 'Open Sans Variable', sans-serif;
+}
+```
diff --git a/website/docs/getting-started/preload.mdx b/website/docs/getting-started/preload.mdx
@@ -0,0 +1,37 @@
+---
+title: Preloading Fonts
+section: Contents
+---
+
+## Preloading Fonts
+
+---
+
+Preloading fonts is a technique used to load fonts before they're required, which can improve your website's performance. However, it's essential to preload only critical fonts and subsets to avoid unnecessarily increasing initial load times.
+
+> **Note:** You can learn more about the `preload` link relation type in the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/preload).
+
+To preload a font, you can use the `preload` link relation type in the `<head>` of your HTML document. However, due to bundler constraints, you must manually import the URL to your font file. This is typically challenging since bundlers like Vite rewrite URLs to hashed filenames.
+
+<br />
+
+Instead, you can use the Vite [static asset directive](https://vitejs.dev/guide/assets.html#explicit-url-imports) `?url` to import the font file URL. For instance, the following code highlights how to preload the Open Sans font:
+
+```jsx
+import '@fontsource-variable/open-sans';
+import openSansWoff2 from '@fontsource-variable/open-sans/files/open-sans-latin-wght-normal.woff2?url';
+
+const App = () => {
+  return (
+    <html lang="en">
+      <head>
+        <link rel="preload" as="font" type="font/woff2" href={openSansWoff2} crossorigin/>
+      </head>
+    </html>
+  );
+};
+```
+
+> **Note:** Avoid preloading all font files in your project, as this may lead to increased initial load times. Only preload critical fonts and subsets that are essential for the initial page display, such as the latin subset only.
+> <br />
+> Additionally, preloading can have negative effects on Core Web Vitals if not used correctly. See the [Web Vitals](https://web.dev/articles/preload-critical-assets#effects_of_preloading_on_core_web_vitals) article for more information.
diff --git a/website/docs/sidebar.json b/website/docs/sidebar.json
@@ -5,6 +5,8 @@
 			"install": "Install",
 			"variable": "Variable Fonts",
 			"subsets": "Individual Subsets",
+			"display": "Font Display",
+			"preload": "Preload",
 			"cdn": "CDN"
 		},
 		"Icons": {