From e0bd04f641e4d34ba23c2e929dcdb6b87d6e13cc Mon Sep 17 00:00:00 2001
From: Zeno Kapitein <zeno@gitbook.io>
Date: Tue, 25 Aug 2026 12:08:03 +0200
Subject: [PATCH] Render headings with the site's heading font (#4531)

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---
 .changeset/site-heading-font.md               |  5 ++
 bun.lock                                      |  4 +-
 package.json                                  |  2 +-
 packages/gitbook/e2e/customers.spec.ts        |  5 --
 .../gitbook/src/components/AIChat/AIChat.tsx  |  2 +-
 .../src/components/DocumentView/Heading.tsx   |  1 +
 .../components/Embeddable/EmbeddableFrame.tsx |  2 +-
 .../components/Footer/FooterLinksGroup.tsx    |  2 +-
 .../src/components/Header/HeaderLogo.tsx      |  1 +
 .../gitbook/src/components/PDF/PDFPage.tsx    |  8 ++-
 .../src/components/PageBody/PageHeader.tsx    |  1 +
 .../RootLayout/CustomizationRootLayout.tsx    | 10 +++
 .../src/components/RootLayout/globals.css     | 11 ++++
 .../components/Search/LocalSearchResults.tsx  |  2 +-
 .../Search/SearchPageResultItem.tsx           |  2 +-
 .../SiteOAuthConsent/ConsentScreen.tsx        |  6 +-
 .../components/SitePage/SitePageNotFound.tsx  | 12 +++-
 .../TableOfContents/PageGroupItem.tsx         |  2 +-
 packages/gitbook/src/fonts/custom.ts          |  8 ++-
 packages/gitbook/src/fonts/default.ts         | 15 +++--
 packages/gitbook/src/fonts/heading.test.ts    | 64 +++++++++++++++++++
 packages/gitbook/src/fonts/heading.ts         | 21 ++++++
 packages/gitbook/src/fonts/index.ts           |  9 ++-
 packages/gitbook/src/fonts/types.ts           |  3 +
 packages/gitbook/tailwind.config.ts           |  2 +
 25 files changed, 166 insertions(+), 34 deletions(-)
 create mode 100644 .changeset/site-heading-font.md
 create mode 100644 packages/gitbook/src/fonts/heading.test.ts
 create mode 100644 packages/gitbook/src/fonts/heading.ts

diff --git a/.changeset/site-heading-font.md b/.changeset/site-heading-font.md
new file mode 100644
index 000000000..f31cc2a09
--- /dev/null
+++ b/.changeset/site-heading-font.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Render headings with the site's heading font when one is configured, falling back to the main font otherwise.
diff --git a/bun.lock b/bun.lock
index 82752faa5..aea449415 100644
--- a/bun.lock
+++ b/bun.lock
@@ -354,7 +354,7 @@
   },
   "catalog": {
     "@base-ui/react": "^1.7.0",
-    "@gitbook/api": "0.195.0",
+    "@gitbook/api": "0.196.0",
     "@scalar/api-client-react": "^1.3.46",
     "@tsconfig/node20": "^20.1.6",
     "@tsconfig/strictest": "^2.0.6",
@@ -726,7 +726,7 @@
 
     "@fortawesome/fontawesome-svg-core": ["@fortawesome/fontawesome-svg-core@7.2.0", "", { "dependencies": { "@fortawesome/fontawesome-common-types": "7.2.0" } }, "sha512-6639htZMjEkwskf3J+e6/iar+4cTNM9qhoWuRfj9F3eJD6r7iCzV1SWnQr2Mdv0QT0suuqU8BoJCZUyCtP9R4Q=="],
 
-    "@gitbook/api": ["@gitbook/api@0.195.0", "", { "dependencies": { "event-iterator": "^2.0.0", "eventsource-parser": "^3.0.0" } }, "sha512-66OGIiiKUfHB7dF8fb9Ai8PkhQldD4SSQXHZ+X+SSEki2WXpgn6ze+PEXRQvDsJj2JKEvD9A7FfaGzUYiYn9hA=="],
+    "@gitbook/api": ["@gitbook/api@0.196.0", "", { "dependencies": { "event-iterator": "^2.0.0", "eventsource-parser": "^3.0.0" } }, "sha512-14f3LXiZljPuxFtYbsdH9mkXN4jucRBnF3QpSACuACDdvJHpTqGsCe52chg3nj72XBbMjD57BsXGklY+IYz9gw=="],
 
     "@gitbook/browser-types": ["@gitbook/browser-types@workspace:packages/browser-types"],
 
diff --git a/package.json b/package.json
index 7917ffa56..4e3cfc099 100644
--- a/package.json
+++ b/package.json
@@ -48,7 +48,7 @@
             "@tsconfig/strictest": "^2.0.6",
             "@tsconfig/node20": "^20.1.6",
             "@base-ui/react": "^1.7.0",
-            "@gitbook/api": "0.195.0",
+            "@gitbook/api": "0.196.0",
             "@scalar/api-client-react": "^1.3.46",
             "@types/react": "^19.0.0",
             "@types/react-dom": "^19.0.0",
diff --git a/packages/gitbook/e2e/customers.spec.ts b/packages/gitbook/e2e/customers.spec.ts
index 7f7ba2abf..692d428d4 100644
--- a/packages/gitbook/e2e/customers.spec.ts
+++ b/packages/gitbook/e2e/customers.spec.ts
@@ -308,11 +308,6 @@ const testCases: TestsCase[] = [
         contentBaseURL: 'https://docs.triumpharcade.com',
         tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
-    {
-        name: 'docs.nats.io',
-        contentBaseURL: 'https://docs.nats.io',
-        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
-    },
     {
         name: 'help.glpi-project.org',
         contentBaseURL: 'https://help.glpi-project.org',
diff --git a/packages/gitbook/src/components/AIChat/AIChat.tsx b/packages/gitbook/src/components/AIChat/AIChat.tsx
index ab83ba530..1c0e8163a 100644
--- a/packages/gitbook/src/components/AIChat/AIChat.tsx
+++ b/packages/gitbook/src/components/AIChat/AIChat.tsx
@@ -260,7 +260,7 @@ export function AIChatBody(props: {
                             </div>
                             <div className="flex flex-col items-start gap-1 [@container(min-height:400px)]:items-center">
                                 <h5
-                                    className="animate-blur-in-slow text-lg font-bold leading-tight text-tint-strong [@container(min-height:400px)]:text-center"
+                                    className="animate-blur-in-slow font-heading text-lg font-bold leading-tight text-tint-strong [@container(min-height:400px)]:text-center"
                                     style={{ animationDelay: '.5s' }}
                                     data-testid="ai-chat-greeting-title"
                                 >
diff --git a/packages/gitbook/src/components/DocumentView/Heading.tsx b/packages/gitbook/src/components/DocumentView/Heading.tsx
index b61433a0b..dc1a8271d 100644
--- a/packages/gitbook/src/components/DocumentView/Heading.tsx
+++ b/packages/gitbook/src/components/DocumentView/Heading.tsx
@@ -31,6 +31,7 @@ export async function Heading(props: BlockProps<DocumentBlockHeading>) {
             className={tcls(
                 textStyle.textSize,
                 'heading',
+                'font-heading',
                 'pdf-heading',
                 'block',
                 'pr-6',
diff --git a/packages/gitbook/src/components/Embeddable/EmbeddableFrame.tsx b/packages/gitbook/src/components/Embeddable/EmbeddableFrame.tsx
index 3d791824d..44b8fafa3 100644
--- a/packages/gitbook/src/components/Embeddable/EmbeddableFrame.tsx
+++ b/packages/gitbook/src/components/Embeddable/EmbeddableFrame.tsx
@@ -87,7 +87,7 @@ export function EmbeddableFrameBody(props: { children: React.ReactNode; classNam
 export function EmbeddableFrameTitle(props: { children: React.ReactNode }) {
     const { children } = props;
 
-    return <div className="font-bold">{children}</div>;
+    return <div className="font-heading font-bold">{children}</div>;
 }
 
 export function EmbeddableFrameClose() {
diff --git a/packages/gitbook/src/components/Footer/FooterLinksGroup.tsx b/packages/gitbook/src/components/Footer/FooterLinksGroup.tsx
index 838ecda07..30e2f1853 100644
--- a/packages/gitbook/src/components/Footer/FooterLinksGroup.tsx
+++ b/packages/gitbook/src/components/Footer/FooterLinksGroup.tsx
@@ -19,7 +19,7 @@ export function FooterLinksGroup(props: {
 
     return (
         <nav className="flex flex-col gap-4 text-sm">
-            <h4 className="font-semibold">{title}</h4>
+            <h4 className="font-heading font-semibold">{title}</h4>
             <ul className="flex flex-col items-start gap-4">
                 {group.links.map((link, index) => {
                     return (
diff --git a/packages/gitbook/src/components/Header/HeaderLogo.tsx b/packages/gitbook/src/components/Header/HeaderLogo.tsx
index 557d046bd..6f9bb6c98 100644
--- a/packages/gitbook/src/components/Header/HeaderLogo.tsx
+++ b/packages/gitbook/src/components/Header/HeaderLogo.tsx
@@ -91,6 +91,7 @@ function LogoFallback(props: HeaderLogoProps) {
                     'tracking-tight',
                     'max-w-[18ch]',
                     'lg:max-w-[24ch]',
+                    'font-heading',
                     'font-semibold',
                     'ms-3',
                     'text-base/tight',
diff --git a/packages/gitbook/src/components/PDF/PDFPage.tsx b/packages/gitbook/src/components/PDF/PDFPage.tsx
index ca0d0d24d..c85f9c386 100644
--- a/packages/gitbook/src/components/PDF/PDFPage.tsx
+++ b/packages/gitbook/src/components/PDF/PDFPage.tsx
@@ -180,7 +180,9 @@ async function PDFSpaceIntro(props: { space: Space; customization: SiteCustomiza
     return (
         <PrintPage isFirst>
             <div className="flex items-center justify-center py-12">
-                <h1 className="text-6xl font-bold">{customization.title ?? space.title}</h1>
+                <h1 className="font-heading text-6xl font-bold">
+                    {customization.title ?? space.title}
+                </h1>
             </div>
         </PrintPage>
     );
@@ -192,7 +194,7 @@ async function PDFPageGroup(props: { space: Space; page: RevisionPageGroup }) {
     return (
         <PrintPage id={getPagePDFContainerId(page)}>
             <div className="mt-10 flex break-before-page items-center justify-center py-12 print:mt-0">
-                <h1 className="text-5xl font-bold">{page.title}</h1>
+                <h1 className="font-heading text-5xl font-bold">{page.title}</h1>
             </div>
         </PrintPage>
     );
@@ -207,7 +209,7 @@ async function PDFPageDocument(props: {
 
     return (
         <PrintPage id={getPagePDFContainerId(page)}>
-            <h1 className="text-4xl font-bold">{page.title}</h1>
+            <h1 className="font-heading text-4xl font-bold">{page.title}</h1>
             {page.description ? (
                 <p className="mb-3 mt-2 decoration-primary/6">{page.description}</p>
             ) : null}
diff --git a/packages/gitbook/src/components/PageBody/PageHeader.tsx b/packages/gitbook/src/components/PageBody/PageHeader.tsx
index ebe6a3b1f..e6cdfbad5 100644
--- a/packages/gitbook/src/components/PageBody/PageHeader.tsx
+++ b/packages/gitbook/src/components/PageBody/PageHeader.tsx
@@ -242,6 +242,7 @@ export async function PageHeader(props: {
                         '@xs:text-3xl',
                         '@lg:text-4xl',
                         'leading-tight',
+                        'font-heading',
                         'font-bold',
                         'flex',
                         'items-center',
diff --git a/packages/gitbook/src/components/RootLayout/CustomizationRootLayout.tsx b/packages/gitbook/src/components/RootLayout/CustomizationRootLayout.tsx
index c3f2d9cb7..62db370e6 100644
--- a/packages/gitbook/src/components/RootLayout/CustomizationRootLayout.tsx
+++ b/packages/gitbook/src/components/RootLayout/CustomizationRootLayout.tsx
@@ -31,6 +31,7 @@ import {
     type FontData,
     generateEmojiFontFacesCSS,
     getFontData,
+    getHeadingFont,
 } from '@/fonts';
 import './globals.css';
 import { getContentLocale, getSpaceLanguage } from '@/intl/server';
@@ -99,10 +100,16 @@ export async function CustomizationRootLayout(props: {
         customization.styling.monospaceFont ?? DEFAULT_MONOSPACE_FONT,
         'mono'
     );
+    // Only set when headings use a font of their own; otherwise they inherit `--font-content`.
+    const headingFont = getHeadingFont(customization);
+    const headingFontData = headingFont ? getFontData(headingFont, 'heading') : null;
 
     // Preconnect and preload custom fonts if needed
     preloadFont(fontData);
     preloadFont(monospaceFontData);
+    if (headingFontData) {
+        preloadFont(headingFontData);
+    }
     const iconStyle = getCustomizationIconStyle(customization);
     const iconSources = await getInlineIconSources([
         ...getDefaultInlineIconSourceRequests(iconStyle),
@@ -132,6 +139,8 @@ export async function CustomizationRootLayout(props: {
                 typeof customization.styling.font === 'string'
                     ? `font-${customization.styling.font}`
                     : null,
+                headingFont ? 'has-heading-font' : null,
+                typeof headingFont === 'string' ? `heading-font-${headingFont}` : null,
 
                 // Set the dark/light class statically to avoid flashing and make it work when JS is disabled
                 (forcedTheme ?? customization.themes.default) === CustomizationDefaultThemeMode.Dark
@@ -154,6 +163,7 @@ export async function CustomizationRootLayout(props: {
                 <style>{generateEmojiFontFacesCSS()}</style>
                 <style>{fontData.fontFaceRules}</style>
                 <style>{monospaceFontData.fontFaceRules}</style>
+                {headingFontData ? <style>{headingFontData.fontFaceRules}</style> : null}
 
                 {/* Inject a script to detect if the announcmeent banner has been dismissed */}
                 {'announcement' in customization && customization.announcement?.enabled ? (
diff --git a/packages/gitbook/src/components/RootLayout/globals.css b/packages/gitbook/src/components/RootLayout/globals.css
index 2110b127a..965381d29 100644
--- a/packages/gitbook/src/components/RootLayout/globals.css
+++ b/packages/gitbook/src/components/RootLayout/globals.css
@@ -375,6 +375,17 @@ html.font-Lato {
   font-variant-ligatures: no-common-ligatures;
 }
 
+/* Headings with a font of their own opt out of the content font's ligature workaround. */
+html.has-heading-font .font-heading {
+  font-variant-ligatures: normal;
+}
+
+/* Lato needs the workaround wherever it is used, the heading font included. Declared after the
+   opt-out above so it wins at equal specificity. */
+html.heading-font-Lato .font-heading {
+  font-variant-ligatures: no-common-ligatures;
+}
+
 /* Code blocks */
 /* Shiki themes can define font styling (style, weight, decoration) via CSS variables.
  * These variables are prefixed with --shiki-{mode}-{property} and allow themes to customize
diff --git a/packages/gitbook/src/components/Search/LocalSearchResults.tsx b/packages/gitbook/src/components/Search/LocalSearchResults.tsx
index c12f32acc..e190c5b11 100644
--- a/packages/gitbook/src/components/Search/LocalSearchResults.tsx
+++ b/packages/gitbook/src/components/Search/LocalSearchResults.tsx
@@ -81,7 +81,7 @@ function LocalSearchResultCard({
                         <Icon icon={result.icon as IconName} className="size-4" />
                     </span>
                 ) : null}
-                <p className="grow truncate text-sm font-semibold leading-snug text-tint-strong">
+                <p className="grow truncate font-heading text-sm font-semibold leading-snug text-tint-strong">
                     {result.title}
                 </p>
                 <span className="ml-auto shrink-0 text-tint-subtle">
diff --git a/packages/gitbook/src/components/Search/SearchPageResultItem.tsx b/packages/gitbook/src/components/Search/SearchPageResultItem.tsx
index 4eefa387e..6f77528ee 100644
--- a/packages/gitbook/src/components/Search/SearchPageResultItem.tsx
+++ b/packages/gitbook/src/components/Search/SearchPageResultItem.tsx
@@ -72,7 +72,7 @@ export const SearchPageResultItem = React.forwardRef(function SearchPageResultIt
             {...rest}
         >
             <Breadcrumbs breadcrumbs={item.breadcrumbs} />
-            <p className="line-clamp-1 text-base font-semibold leading-snug text-tint-strong">
+            <p className="line-clamp-1 font-heading text-base font-semibold leading-snug text-tint-strong">
                 <HighlightQuery query={query} text={item.title} />
             </p>
             <div
diff --git a/packages/gitbook/src/components/SiteOAuthConsent/ConsentScreen.tsx b/packages/gitbook/src/components/SiteOAuthConsent/ConsentScreen.tsx
index 6b93d3f6b..fe6432f87 100644
--- a/packages/gitbook/src/components/SiteOAuthConsent/ConsentScreen.tsx
+++ b/packages/gitbook/src/components/SiteOAuthConsent/ConsentScreen.tsx
@@ -37,7 +37,7 @@ export async function ConsentScreen(props: {
                     </div>
 
                     {/* Request statement — toned down, with the client and site names emphasized. */}
-                    <h1 className="text-xl leading-snug text-tint sm:text-2xl">
+                    <h1 className="font-heading text-xl leading-snug text-tint sm:text-2xl">
                         {t(
                             language,
                             'auth_consent_request',
@@ -69,7 +69,7 @@ export async function ConsentScreen(props: {
 
                             <div className="flex min-w-0 flex-col gap-0.5">
                                 <div className="flex items-center gap-x-2 gap-y-1">
-                                    <h2 className="text-base font-semibold text-tint-strong">
+                                    <h2 className="font-heading text-base font-semibold text-tint-strong">
                                         {client.name}
                                     </h2>
                                     <ClientTrustBadge
@@ -219,7 +219,7 @@ export async function ConsentError(props: {
                     <Icon icon="circle-exclamation" className="size-6" />
                 </span>
                 <div className="flex flex-col gap-1">
-                    <h1 className="text-lg font-semibold text-tint-strong">{title}</h1>
+                    <h1 className="font-heading text-lg font-semibold text-tint-strong">{title}</h1>
                     <p className="text-tint">{message}</p>
                 </div>
             </ConsentCard>
diff --git a/packages/gitbook/src/components/SitePage/SitePageNotFound.tsx b/packages/gitbook/src/components/SitePage/SitePageNotFound.tsx
index 26646aca8..94e394fc6 100644
--- a/packages/gitbook/src/components/SitePage/SitePageNotFound.tsx
+++ b/packages/gitbook/src/components/SitePage/SitePageNotFound.tsx
@@ -117,7 +117,13 @@ export function SitePageNotFound() {
 
                     <div className="flex w-full flex-col items-center gap-8">
                         <div className="flex w-full flex-col items-center gap-2 rounded-3xl">
-                            <h1 className={tcls('text-3xl', 'font-semibold', 'text-tint-strong')}>
+                            <h1
+                                className={tcls(
+                                    'text-3xl',
+                                    'font-semibold font-heading',
+                                    'text-tint-strong'
+                                )}
+                            >
                                 {t(
                                     language,
                                     adaptiveAuthLoginHref
@@ -197,7 +203,9 @@ function NotFoundSuggestions(props: { suggestions: RelatedPage[] | null }) {
 
     return loading || hasResults ? (
         <div className="-mt-4 flex w-full flex-col gap-2 border-tint-subtle bg-tint-subtle p-8 pt-10 theme-muted:bg-tint theme-gradient:border rounded-corners:rounded-b-xl circular-corners:rounded-b-3xl">
-            <h2 className="font-medium text-tint">{t(language, 'notfound_suggestions_title')}</h2>
+            <h2 className="font-heading font-medium text-tint">
+                {t(language, 'notfound_suggestions_title')}
+            </h2>
             <ul className="flex flex-col gap-2">
                 {loading ? (
                     <SkeletonList items={RELATED_PAGES_COUNT} className="my-0.75 max-w-md" />
diff --git a/packages/gitbook/src/components/TableOfContents/PageGroupItem.tsx b/packages/gitbook/src/components/TableOfContents/PageGroupItem.tsx
index 5e5b8aac3..4acbbcd4e 100644
--- a/packages/gitbook/src/components/TableOfContents/PageGroupItem.tsx
+++ b/packages/gitbook/src/components/TableOfContents/PageGroupItem.tsx
@@ -58,7 +58,7 @@ export function PageGroupItem(props: { page: ClientTOCPageGroup; isFirst?: boole
                     className={tcls(
                         ToCButtonItemStyles,
                         'toc-group min-h-8 w-full border-0 text-left',
-                        'font-semibold text-xs uppercase tracking-wide',
+                        'font-heading font-semibold text-xs uppercase tracking-wide',
                         'appearance-none',
                         '[&_.toc-group-chevron]:transition-opacity',
                         'hover:[&_.toc-group-chevron]:opacity-11',
diff --git a/packages/gitbook/src/fonts/custom.ts b/packages/gitbook/src/fonts/custom.ts
index a213d87e3..e4dc48b95 100644
--- a/packages/gitbook/src/fonts/custom.ts
+++ b/packages/gitbook/src/fonts/custom.ts
@@ -1,17 +1,19 @@
 import type { CustomizationFontDefinitionInput } from '@gitbook/api';
 
+import type { FontRole } from './types';
+
 /**
- * Define the custom font faces and set the --font-content or --font-mono variable
+ * Define the custom font faces and set the --font-content, --font-heading or --font-mono variable
  * to the custom font name.
  */
 export function generateFontFacesCSS(
     customFont: CustomizationFontDefinitionInput,
-    type: 'content' | 'mono'
+    type: FontRole
 ): string {
     const { fontFaces } = customFont;
     const fontFamilyName = `CustomFont_${type}`;
     const fontVariableName = `--font-${type}`;
-    const fallbackFont = type === 'content' ? 'sans-serif' : 'monospace';
+    const fallbackFont = type === 'mono' ? 'monospace' : 'sans-serif';
 
     // Generate font face declarations for all weights
     const fontFaceDeclarations = fontFaces
diff --git a/packages/gitbook/src/fonts/default.ts b/packages/gitbook/src/fonts/default.ts
index f8c445f6b..69b4756aa 100644
--- a/packages/gitbook/src/fonts/default.ts
+++ b/packages/gitbook/src/fonts/default.ts
@@ -2,21 +2,22 @@ import { CustomizationDefaultMonospaceFont } from '@gitbook/api';
 
 import { EMOJI_FONT, type FontName } from './definitions';
 import faces from './generated/faces.json';
-import type { FontFacesData, FontFamilyData } from './types';
+import type { FontFacesData, FontFamilyData, FontRole } from './types';
 import { getAssetURL } from '@/lib/assets';
 
 const fontFaces = faces as FontFacesData;
 
-// The rules only vary by font, and every page renders a few dozen of them.
-const cache = new Map<FontName, string>();
+// The rules only vary by font and the variable they bind, and every page renders a few dozen.
+const cache = new Map<string, string>();
 
 /** Used until the cache has warmed up for sites saved before the setting existed. */
 export const DEFAULT_MONOSPACE_FONT = CustomizationDefaultMonospaceFont.IBMPlexMono;
 
 // Emitted per picked family and inlined in the head, so a page never carries the other 20 families
 // the way a shared `next/font` stylesheet did.
-export function generateDefaultFontFacesCSS(font: FontName): string {
-    const cached = cache.get(font);
+export function generateDefaultFontFacesCSS(font: FontName, role?: FontRole): string {
+    const key = role ? `${font}:${role}` : font;
+    const cached = cache.get(key);
     if (cached !== undefined) {
         return cached;
     }
@@ -33,12 +34,12 @@ export function generateDefaultFontFacesCSS(font: FontName): string {
             )
         ),
         generateFallbackFace(family),
-        `:root { ${family.variable}: ${family.fontFamilyValue}; }`,
+        `:root { ${role ? `--font-${role}` : family.variable}: ${family.fontFamilyValue}; }`,
     ]
         .filter(Boolean)
         .join('\n');
 
-    cache.set(font, css);
+    cache.set(key, css);
     return css;
 }
 
diff --git a/packages/gitbook/src/fonts/heading.test.ts b/packages/gitbook/src/fonts/heading.test.ts
new file mode 100644
index 000000000..f15afd54d
--- /dev/null
+++ b/packages/gitbook/src/fonts/heading.test.ts
@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'bun:test';
+
+import { CustomizationDefaultFont, type SiteCustomizationSettings } from '@gitbook/api';
+
+import { getHeadingFont } from './heading';
+import { defaultCustomization } from '@/lib/utils';
+
+const CUSTOM_FONT = {
+    id: 'font_1',
+    custom: true,
+    fontFamily: 'Segoe UI',
+    fontFaces: [{ weight: 400 as const, sources: [{ url: 'https://example.com/segoe.woff2' }] }],
+};
+
+function customization(
+    styling: Partial<SiteCustomizationSettings['styling']>
+): SiteCustomizationSettings {
+    const base = defaultCustomization();
+    return { ...base, styling: { ...base.styling, ...styling } };
+}
+
+describe('getHeadingFont', () => {
+    it('returns null when no heading font is set', () => {
+        expect(getHeadingFont(customization({}))).toBeNull();
+    });
+
+    it('returns the heading font when it differs from the content font', () => {
+        const settings = customization({
+            font: CustomizationDefaultFont.Inter,
+            headingFont: CustomizationDefaultFont.Merriweather,
+        });
+        expect(getHeadingFont(settings)).toBe(CustomizationDefaultFont.Merriweather);
+    });
+
+    it('returns null when the heading font is the content font', () => {
+        const settings = customization({
+            font: CustomizationDefaultFont.Inter,
+            headingFont: CustomizationDefaultFont.Inter,
+        });
+        expect(getHeadingFont(settings)).toBeNull();
+    });
+
+    it('compares custom fonts by id', () => {
+        expect(
+            getHeadingFont(customization({ font: CUSTOM_FONT, headingFont: CUSTOM_FONT }))
+        ).toBeNull();
+        expect(
+            getHeadingFont(
+                customization({
+                    font: CUSTOM_FONT,
+                    headingFont: { ...CUSTOM_FONT, id: 'font_2' },
+                })
+            )
+        ).toMatchObject({ id: 'font_2' });
+    });
+
+    it('ignores a custom heading font when the content font is a default one', () => {
+        const settings = customization({
+            font: CustomizationDefaultFont.Inter,
+            headingFont: CUSTOM_FONT,
+        });
+        expect(getHeadingFont(settings)).toMatchObject({ id: 'font_1' });
+    });
+});
diff --git a/packages/gitbook/src/fonts/heading.ts b/packages/gitbook/src/fonts/heading.ts
new file mode 100644
index 000000000..f679d951c
--- /dev/null
+++ b/packages/gitbook/src/fonts/heading.ts
@@ -0,0 +1,21 @@
+import type { CustomizationFont, SiteCustomizationSettings } from '@gitbook/api';
+
+/**
+ * Font to render headings with, or `null` when they should use the content font.
+ */
+export function getHeadingFont(customization: SiteCustomizationSettings): CustomizationFont | null {
+    const { headingFont, font } = customization.styling;
+    if (!headingFont) {
+        return null;
+    }
+
+    // Headings only need their own faces when they don't already come with the content font.
+    return isSameFont(headingFont, font) ? null : headingFont;
+}
+
+function isSameFont(a: CustomizationFont, b: CustomizationFont): boolean {
+    if (typeof a === 'string' || typeof b === 'string') {
+        return a === b;
+    }
+    return a.id === b.id;
+}
diff --git a/packages/gitbook/src/fonts/index.ts b/packages/gitbook/src/fonts/index.ts
index 294d7c19d..47abd178a 100644
--- a/packages/gitbook/src/fonts/index.ts
+++ b/packages/gitbook/src/fonts/index.ts
@@ -6,8 +6,11 @@ import type {
 
 import { generateFontFacesCSS, getFontSourcesToPreload } from './custom';
 import { generateDefaultFontFacesCSS } from './default';
+import type { FontRole } from './types';
 
 export { DEFAULT_MONOSPACE_FONT, generateEmojiFontFacesCSS } from './default';
+export type { FontRole } from './types';
+export { getHeadingFont } from './heading';
 
 /**
  * Represents font data for either a default font or a custom font
@@ -39,12 +42,14 @@ interface CustomFontData extends BaseFontData {
  */
 export function getFontData(
     font: CustomizationFont | CustomizationMonospaceFont,
-    type: 'content' | 'mono'
+    type: FontRole
 ): FontData {
     if (typeof font === 'string') {
         return {
             type: 'default',
-            fontFaceRules: generateDefaultFontFacesCSS(font),
+            // The heading font shares the default families with the content font, so it has to bind
+            // the family to `--font-heading` rather than the family's own variable.
+            fontFaceRules: generateDefaultFontFacesCSS(font, type === 'heading' ? type : undefined),
         };
     }
 
diff --git a/packages/gitbook/src/fonts/types.ts b/packages/gitbook/src/fonts/types.ts
index 2129ed610..8936c6fdb 100644
--- a/packages/gitbook/src/fonts/types.ts
+++ b/packages/gitbook/src/fonts/types.ts
@@ -1,3 +1,6 @@
+/** Which of the document's font variables a picked family is bound to. */
+export type FontRole = 'content' | 'heading' | 'mono';
+
 export interface FontVariantData {
     weight: string;
     style: string;
diff --git a/packages/gitbook/tailwind.config.ts b/packages/gitbook/tailwind.config.ts
index cf95c432b..40c8662d6 100644
--- a/packages/gitbook/tailwind.config.ts
+++ b/packages/gitbook/tailwind.config.ts
@@ -71,6 +71,8 @@ const config: Config = {
             },
             fontFamily: {
                 sans: ['var(--font-content)'],
+                // Sites without a heading font of their own fall back to the content font.
+                heading: ['var(--font-heading, var(--font-content))'],
                 mono: ['var(--font-mono)'],
                 emoji: [
                     'Apple Color Emoji',