Using Web Fonts with Astro Starlight

Mar 16, 2025

I tried using web fonts with Astro’s documentation template Starlight, so here’s a memo for future reference.

Setting up Fontsource Fonts

There are several ways to use web fonts with Starlight, but here I’ll introduce the method using Fontsource.

Fontsource is a package that allows you to easily select and install fonts from font catalogs like Google Fonts and Adobe Fonts.

Installing the font package

Install your preferred font package from the Fontsource page.

For example, if you want to use Geist:
- pnpm
- npm
- Yarn
Terminal window
pnpm add @fontsource-variable/geist
Terminal window
npm install @fontsource-variable/geist
Terminal window
yarn add @fontsource-variable/geist

Configuring astro.config.mjs

Add the Fontsource CSS file to the customCss array in your astro.config.mjs file:

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
integrations: [
    starlight({
    title: 'Documentation with Custom Font',
    customCss: [
        '@fontsource-variable/geist',
    ],
    }),
],
});

Applying the Font

To apply the configured font to your site, specify the font name in a custom CSS file.

Applying to the entire site

:root {
  --sl-font: 'Geist Variable', serif;
}

Applying to specific elements only

main {
  font-family: 'Geist Variable', serif;
}

Applying with Tailwind CSS

Set up the font in your tailwind.config.js file:

import starlightPlugin from '@astrojs/starlight-tailwind';

/** @type {import('tailwindcss').Config} */
export default {
  content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
  theme: {
    extend: {
      fontFamily: {
        sans: ['Geist Variable'],
      },
    },
  },
  plugins: [starlightPlugin()],
};