feat: integrate Astro fonts API with Google Sans Code font (#602)

- Add Google Sans Code font and make it the default font - Font is preloaded with latin subset and weight 400 and style normal for optimal performance - Add font configuration section in how to config docs
2026-08-14 07:33:07 +08:00 · 2026-01-10 21:08:31 +07:00
parent 5bb8e405bb
commit 698295d23d
5 changed files with 93 additions and 5 deletions
@@ -1,4 +1,4 @@
-import { defineConfig, envField } from "astro/config";
+import { defineConfig, envField, fontProviders } from "astro/config";
 import tailwindcss from "@tailwindcss/vite";
 import sitemap from "@astrojs/sitemap";
 import remarkToc from "remark-toc";
@@ -59,5 +59,15 @@ export default defineConfig({
  },
  experimental: {
    preserveScriptOrder: true,
+    fonts: [
+      {
+        name: "Google Sans Code",
+        cssVariable: "--font-google-sans-code",
+        provider: fontProviders.google(),
+        fallbacks: ["monospace"],
+        weights: [300, 400, 500, 600, 700],
+        styles: ["normal", "italic"],
+      },
+    ],
  },
 });
@@ -1,7 +1,7 @@
 ---
 author: Sat Naing
 pubDatetime: 2022-09-23T04:58:53Z
-modDatetime: 2025-03-20T03:15:57.792Z
+modDatetime: 2026-01-10T13:04:53.851Z
 title: How to configure AstroPaper theme
 slug: how-to-configure-astropaper-theme
 featured: true
@@ -195,6 +195,76 @@ You can configure share links in `SHARE_LINKS` object inside `src/constants.ts`.

 ![An arrow pointing at share link icons](https://github.com/user-attachments/assets/4f930b68-b625-45df-8c41-e076dd2b838e)

+## Configuring fonts
+
+AstroPaper uses Astro's [experimental fonts API](https://docs.astro.build/en/reference/experimental-flags/fonts/) with [Google Sans Code](https://fonts.google.com/specimen/Google+Sans+Code) as the default font. This provides consistent typography across all platforms with automatic font optimizations including preloading and caching.
+
+### Using the default font
+
+The font is automatically configured in `astro.config.ts` and loaded in `Layout.astro`. No additional configuration is needed to use the default Google Sans Code font.
+
+### Customizing the font
+
+To use a different font, you need to update three places:
+
+1. **Update the font configuration in `astro.config.ts`:**
+
+```ts file=astro.config.ts
+import { defineConfig, fontProviders } from "astro/config";
+
+export default defineConfig({
+  // ...
+  experimental: {
+    fonts: [
+      {
+        name: "Your Font Name", // [!code highlight]
+        cssVariable: "--font-your-font", // [!code highlight]
+        provider: fontProviders.google(),
+        fallbacks: ["monospace"],
+        weights: [300, 400, 500, 600, 700],
+        styles: ["normal", "italic"],
+      },
+    ],
+  },
+});
+```
+
+1. **Update the Font component in `Layout.astro`:**
+
+```astro file=src/layouts/Layout.astro
+---
+import { Font } from "astro:assets";
+// ...
+---
+
+<head>
+  <!-- ... -->
+  // [!code highlight:4]
+  <Font
+    cssVariable="--font-your-font"
+    preload={[{ subset: "latin", weight: 400, style: "normal" }]}
+  />
+  <!-- ... -->
+</head>
+```
+
+1. **Update the CSS variable mapping in `global.css`:**
+
+```css file=src/styles/global.css
+@theme inline {
+  --font-app: var(--font-your-font); /* [!code highlight] */
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-accent: var(--accent);
+  --color-muted: var(--muted);
+  --color-border: var(--border);
+}
+```
+
+The `--font-app` variable is used throughout the theme via the `font-app` Tailwind utility class, so updating this single variable will apply your custom font everywhere.
+
+> **Note**: Make sure the font name matches exactly as it appears on [Google Fonts](https://fonts.google.com). For other font providers or local fonts, refer to the [Astro Experimental Fonts API documentation](https://docs.astro.build/en/reference/experimental-flags/fonts/).
+
 ## Conclusion

 This is the brief specification of how you can customize this theme. You can customize more if you know some coding. For customizing styles, please read [this article](https://astro-paper.pages.dev/posts/customizing-astropaper-theme-color-schemes/). Thanks for reading.✌🏻
@@ -1,4 +1,5 @@
 ---
+import { Font } from "astro:assets";
 import { ClientRouter } from "astro:transitions";
 import { PUBLIC_GOOGLE_SITE_VERIFICATION } from "astro:env/client";
 import { SITE } from "@/config";
@@ -60,6 +61,12 @@ const structuredData = {
    <link rel="canonical" href={canonicalURL} />
    <meta name="generator" content={Astro.generator} />

+    <!-- Load Font -->
+    <Font
+      cssVariable="--font-google-sans-code"
+      preload={[{ subset: "latin", weight: 400, style: "normal" }]}
+    />
+
    <!-- General Meta Tags -->
    <title>{title}</title>
    <meta name="title" content={title} />
@@ -91,7 +91,7 @@ const backUrl = SITE.showBackButton ? `${Astro.url.pathname}` : "/";

 <style is:global>
  #pagefind-search {
-    --pagefind-ui-font: var(--font-mono);
+    --pagefind-ui-font: var(--font-app);
    --pagefind-ui-text: var(--foreground);
    --pagefind-ui-background: var(--background);
    --pagefind-ui-border: var(--border);
@@ -21,6 +21,7 @@ html[data-theme="dark"] {
 }

@theme inline {
+  --font-app: var(--font-google-sans-code);
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-accent: var(--accent);
@@ -38,7 +39,7 @@ html[data-theme="dark"] {
    @apply overflow-y-scroll scroll-smooth;
  }
  body {
-    @apply flex min-h-svh flex-col bg-background font-mono text-foreground selection:bg-accent/75 selection:text-background;
+    @apply flex min-h-svh flex-col bg-background font-app text-foreground selection:bg-accent/75 selection:text-background;
  }
  a,
  button {
@@ -59,7 +60,7 @@ html[data-theme="dark"] {
 }

 .active-nav {
-  @apply underline decoration-wavy decoration-2 underline-offset-4;
+  @apply underline decoration-wavy decoration-2 underline-offset-8;
 }

 /* Source: https://piccalil.li/blog/a-more-modern-css-reset/ */