From 7cc6090e03c6c007fcf3393bdddac7984e868203 Mon Sep 17 00:00:00 2001
From: Brett Jephson <brett@gitbook.io>
Date: Wed, 29 Apr 2026 16:55:56 +0100
Subject: [PATCH 01/16] load icons as symbols

---
 packages/gitbook/.gitignore                   |   3 +-
 packages/gitbook/package.json                 |   3 +-
 .../gitbook/scripts/generate-icon-symbols.js  |  73 ++++++++++
 packages/gitbook/scripts/generate.sh          |   1 +
 .../icons/symbol/[style]/[icon]/route.ts      |  32 +++++
 .../RootLayout/CustomizationRootLayout.tsx    |  13 +-
 .../RootLayout/IconSpriteDefinitions.tsx      |  56 ++++++++
 .../src/components/SiteLayout/SiteLayout.tsx  |   3 +-
 .../gitbook/src/lib/icons/symbols.test.tsx    | 110 +++++++++++++++
 packages/gitbook/src/lib/icons/symbols.ts     |  81 +++++++++++
 packages/gitbook/src/lib/icons/types.ts       |   6 +
 packages/icons/src/Icon.test.tsx              |  63 +++++++++
 packages/icons/src/Icon.tsx                   |  42 +++++-
 packages/icons/src/IconSymbolLoader.tsx       | 129 ++++++++++++++++++
 packages/icons/src/IconsProvider.tsx          |  23 +++-
 packages/icons/src/index.ts                   |   2 +
 packages/icons/src/symbols.ts                 |  53 +++++++
 packages/icons/tsconfig.json                  |   2 +-
 turbo.json                                    |   2 +-
 19 files changed, 681 insertions(+), 16 deletions(-)
 create mode 100644 packages/gitbook/scripts/generate-icon-symbols.js
 create mode 100644 packages/gitbook/src/app/~gitbook/icons/symbol/[style]/[icon]/route.ts
 create mode 100644 packages/gitbook/src/components/RootLayout/IconSpriteDefinitions.tsx
 create mode 100644 packages/gitbook/src/lib/icons/symbols.test.tsx
 create mode 100644 packages/gitbook/src/lib/icons/symbols.ts
 create mode 100644 packages/gitbook/src/lib/icons/types.ts
 create mode 100644 packages/icons/src/Icon.test.tsx
 create mode 100644 packages/icons/src/IconSymbolLoader.tsx
 create mode 100644 packages/icons/src/symbols.ts

diff --git a/packages/gitbook/.gitignore b/packages/gitbook/.gitignore
index f7a6b34753..f8c2962787 100644
--- a/packages/gitbook/.gitignore
+++ b/packages/gitbook/.gitignore
@@ -32,8 +32,9 @@ screenshots/
 # Generated public files
 /public/~gitbook/static/*
 !/public/~gitbook/static/images
+/.generated/
 
 # cloudflare
 .open-next
 .wrangler
-worker-configuration.d.ts
\ No newline at end of file
+worker-configuration.d.ts
diff --git a/packages/gitbook/package.json b/packages/gitbook/package.json
index f67cb7c6de..9088261887 100644
--- a/packages/gitbook/package.json
+++ b/packages/gitbook/package.json
@@ -118,8 +118,9 @@
         "rss-parser": "^3.13.0"
     },
     "scripts": {
+        "generate:icon-symbols": "node ./scripts/generate-icon-symbols.js",
         "generate": "./scripts/generate.sh",
-        "clean": "rm -rf ./.next && rm -rf ./public/~gitbook/static/icons && rm -rf ./public/~gitbook/static/math",
+        "clean": "rm -rf ./.next && rm -rf ./.generated && rm -rf ./public/~gitbook/static/icons && rm -rf ./public/~gitbook/static/math",
         "dev": "env-cmd --silent -f ../../.env.local next --webpack",
         "build": "next build --webpack",
         "build:local": "GITBOOK_URL=http://localhost:3000 next build --webpack",
diff --git a/packages/gitbook/scripts/generate-icon-symbols.js b/packages/gitbook/scripts/generate-icon-symbols.js
new file mode 100644
index 0000000000..fb5127d955
--- /dev/null
+++ b/packages/gitbook/scripts/generate-icon-symbols.js
@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+const { existsSync } = require('node:fs');
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+const packageJSONPath = require.resolve('@gitbook/fontawesome-pro/package.json');
+const packageRoot = path.dirname(packageJSONPath);
+const outputDirectory = path.resolve(__dirname, '../.generated/icon-symbols');
+const metadataPath = path.join(packageRoot, 'icons', 'metadata', 'icons.json');
+
+const supportedStyles = [
+    'brands',
+    'custom-icons',
+    'duotone',
+    'light',
+    'regular',
+    'sharp-duotone-solid',
+    'sharp-light',
+    'sharp-regular',
+    'sharp-solid',
+    'sharp-thin',
+    'solid',
+    'thin',
+];
+
+const symbolPattern = /<symbol id="([^"]+)" viewBox="([^"]+)">([\s\S]*?)<\/symbol>/g;
+
+async function main() {
+    await fs.rm(outputDirectory, { recursive: true, force: true });
+    await fs.mkdir(outputDirectory, { recursive: true });
+    const iconMetadata = JSON.parse(await fs.readFile(metadataPath, 'utf8'));
+
+    await Promise.all(
+        supportedStyles.map(async (style) => {
+            const spritePath = path.join(packageRoot, 'icons', 'sprites', `${style}.svg`);
+            if (!existsSync(spritePath)) {
+                throw new Error(`Missing sprite file for "${style}": ${spritePath}`);
+            }
+
+            const sprite = await fs.readFile(spritePath, 'utf8');
+            const entries = {};
+
+            for (const match of sprite.matchAll(symbolPattern)) {
+                const [, icon, viewBox, markup] = match;
+                entries[icon] = {
+                    viewBox,
+                    markup,
+                };
+
+                const aliases = iconMetadata[icon]?.aliases?.names ?? [];
+                for (const alias of aliases) {
+                    if (!entries[alias]) {
+                        entries[alias] = entries[icon];
+                    }
+                }
+            }
+
+            await fs.writeFile(
+                path.join(outputDirectory, `${style}.json`),
+                JSON.stringify(entries),
+                'utf8'
+            );
+        })
+    );
+
+    // biome-ignore lint/suspicious/noConsole: CLI output is useful when regenerating manifests.
+    console.log(`Generated ${supportedStyles.length} icon symbol manifests in ${outputDirectory}`);
+}
+
+main().catch((error) => {
+    console.error(`Error generating icon symbols: ${error}`);
+    process.exit(1);
+});
diff --git a/packages/gitbook/scripts/generate.sh b/packages/gitbook/scripts/generate.sh
index a1cfab43bd..28e9aaf830 100755
--- a/packages/gitbook/scripts/generate.sh
+++ b/packages/gitbook/scripts/generate.sh
@@ -5,6 +5,7 @@ set -o pipefail
 
 # Copy the assets
 gitbook-icons ./public/~gitbook/static/icons custom-icons
+bun run generate:icon-symbols
 gitbook-math ./public/~gitbook/static/math
 cp -r ../embed/standalone/ ./public/~gitbook/static/embed
 
diff --git a/packages/gitbook/src/app/~gitbook/icons/symbol/[style]/[icon]/route.ts b/packages/gitbook/src/app/~gitbook/icons/symbol/[style]/[icon]/route.ts
new file mode 100644
index 0000000000..4828323010
--- /dev/null
+++ b/packages/gitbook/src/app/~gitbook/icons/symbol/[style]/[icon]/route.ts
@@ -0,0 +1,32 @@
+import { type NextRequest, NextResponse } from 'next/server';
+
+import { getIconSymbol } from '@/lib/icons/symbols';
+
+function getSymbolId(style: string, icon: string) {
+    const sanitize = (value: string) => value.replace(/[^a-zA-Z0-9_-]/g, '-');
+    return `gb-icon-${sanitize(style)}-${sanitize(icon)}`;
+}
+
+export async function GET(
+    _request: NextRequest,
+    { params }: { params: Promise<{ style: string; icon: string }> }
+) {
+    const { style, icon } = await params;
+    const symbol = await getIconSymbol(style, icon, getSymbolId(style, icon));
+
+    if (!symbol) {
+        return NextResponse.json(
+            {
+                error: 'Symbol not found',
+            },
+            { status: 404 }
+        );
+    }
+
+    return new NextResponse(symbol.symbol, {
+        headers: {
+            'content-type': 'image/svg+xml; charset=utf-8',
+            'cache-control': 'public, max-age=31536000, immutable',
+        },
+    });
+}
diff --git a/packages/gitbook/src/components/RootLayout/CustomizationRootLayout.tsx b/packages/gitbook/src/components/RootLayout/CustomizationRootLayout.tsx
index cbb0a71b71..22583c0675 100644
--- a/packages/gitbook/src/components/RootLayout/CustomizationRootLayout.tsx
+++ b/packages/gitbook/src/components/RootLayout/CustomizationRootLayout.tsx
@@ -27,6 +27,7 @@ import { getContentLocale, getSpaceLanguage } from '@/intl/server';
 import { getAssetURL } from '@/lib/assets';
 import { tcls } from '@/lib/tailwind';
 
+import { IconSpriteDefinitions } from './IconSpriteDefinitions';
 import { RootLayoutClientContexts } from './RootLayoutClientContexts';
 
 import './globals.css';
@@ -76,6 +77,9 @@ export async function CustomizationRootLayout(props: {
     const sidebarStyles = getSidebarStyles(customization);
     const { infoColor, successColor, warningColor, dangerColor } = getSemanticColors(customization);
     const fontData = getFontData(customization.styling.font, 'content');
+    const iconStyle =
+        ('icons' in customization.styling ? apiToIconsStyles[customization.styling.icons] : null) ||
+        IconStyle.Regular;
     // Temporarily add a if here while the cache is being warmed up.
     // We can remove the condition after 14-07-2025.
     const monospaceFontData = customization.styling.monospaceFont
@@ -194,15 +198,14 @@ export async function CustomizationRootLayout(props: {
                             assetsURL: getAssetURL('icons'),
                         },
                     }}
-                    iconStyle={
-                        ('icons' in customization.styling
-                            ? apiToIconsStyles[customization.styling.icons]
-                            : null) || IconStyle.Regular
-                    }
+                    renderMode="symbol"
+                    symbolLoaderURL="/~gitbook/icons/symbol"
+                    iconStyle={iconStyle}
                 >
                     <RootLayoutClientContexts language={language}>
                         {children}
                     </RootLayoutClientContexts>
+                    <IconSpriteDefinitions />
                 </IconsProvider>
             </body>
         </html>
diff --git a/packages/gitbook/src/components/RootLayout/IconSpriteDefinitions.tsx b/packages/gitbook/src/components/RootLayout/IconSpriteDefinitions.tsx
new file mode 100644
index 0000000000..1da2e5fb9c
--- /dev/null
+++ b/packages/gitbook/src/components/RootLayout/IconSpriteDefinitions.tsx
@@ -0,0 +1,56 @@
+import { getIconSymbol } from '@/lib/icons/symbols';
+import {
+    type RegisteredIconSymbol,
+    clearRegisteredServerIconSymbols,
+    getRegisteredServerIconSymbols,
+} from '@gitbook/icons';
+
+/**
+ * Emits the subset of icon symbols that were rendered during the current request.
+ */
+export async function IconSpriteDefinitions() {
+    const registered: Map<string, RegisteredIconSymbol> = new Map(
+        getRegisteredServerIconSymbols().map((symbol: RegisteredIconSymbol) => [
+            `${symbol.style}/${symbol.icon}`,
+            symbol,
+        ])
+    );
+
+    if (registered.size === 0) {
+        return null;
+    }
+
+    const definitions = (
+        await Promise.all(
+            [...registered.values()].map((symbol) => {
+                return getIconSymbol(symbol.style, symbol.icon, symbol.symbolId);
+            })
+        )
+    ).filter((symbol): symbol is NonNullable<typeof symbol> => !!symbol);
+
+    clearRegisteredServerIconSymbols();
+
+    if (!definitions.length) {
+        return null;
+    }
+
+    return (
+        <svg
+            id="gb-icon-sprite-root"
+            data-testid="icon-sprite-root"
+            aria-hidden="true"
+            focusable="false"
+            xmlns="http://www.w3.org/2000/svg"
+            style={{
+                position: 'absolute',
+                width: 0,
+                height: 0,
+                overflow: 'hidden',
+                pointerEvents: 'none',
+            }}
+            dangerouslySetInnerHTML={{
+                __html: definitions.map((symbol) => symbol.symbol).join(''),
+            }}
+        />
+    );
+}
diff --git a/packages/gitbook/src/components/SiteLayout/SiteLayout.tsx b/packages/gitbook/src/components/SiteLayout/SiteLayout.tsx
index 4ccecb7e67..4f48f01c46 100644
--- a/packages/gitbook/src/components/SiteLayout/SiteLayout.tsx
+++ b/packages/gitbook/src/components/SiteLayout/SiteLayout.tsx
@@ -10,7 +10,7 @@ import { LoadIntegrations } from '@/components/Integrations';
 import { SpaceLayout } from '@/components/SpaceLayout';
 import type { VisitorAuthClaims } from '@/lib/adaptive';
 import { buildVersion } from '@/lib/build';
-import { GITBOOK_API_PUBLIC_URL, GITBOOK_ASSETS_URL, GITBOOK_ICONS_URL } from '@/lib/env';
+import { GITBOOK_API_PUBLIC_URL, GITBOOK_ASSETS_URL } from '@/lib/env';
 import { getResizedImageURL } from '@/lib/images';
 import { isSiteIndexable } from '@/lib/seo';
 import { AIContextProvider } from '../AI';
@@ -34,7 +34,6 @@ export async function SiteLayout(props: {
     const scripts = withTracking ? context.scripts : [];
 
     ReactDOM.preconnect(GITBOOK_API_PUBLIC_URL);
-    ReactDOM.preconnect(GITBOOK_ICONS_URL);
     if (GITBOOK_ASSETS_URL) {
         ReactDOM.preconnect(GITBOOK_ASSETS_URL);
     }
diff --git a/packages/gitbook/src/lib/icons/symbols.test.tsx b/packages/gitbook/src/lib/icons/symbols.test.tsx
new file mode 100644
index 0000000000..2129c1a271
--- /dev/null
+++ b/packages/gitbook/src/lib/icons/symbols.test.tsx
@@ -0,0 +1,110 @@
+import { afterEach, describe, expect, it } from 'bun:test';
+import { Icon, IconStyle, IconsProvider, clearRegisteredServerIconSymbols } from '@gitbook/icons';
+import type { NextRequest } from 'next/server';
+import { renderToStaticMarkup } from 'react-dom/server';
+
+import { GET } from '@/app/~gitbook/icons/symbol/[style]/[icon]/route';
+import { IconSpriteDefinitions } from '@/components/RootLayout/IconSpriteDefinitions';
+
+import { getIconSymbol } from './symbols';
+
+afterEach(() => {
+    clearRegisteredServerIconSymbols();
+});
+
+describe('icon symbols', () => {
+    it('loads symbol markup for multiple families', async () => {
+        const regular = await getIconSymbol('regular', 'jar', 'gb-icon-regular-jar');
+        const brand = await getIconSymbol('brands', 'github', 'gb-icon-brands-github');
+        const custom = await getIconSymbol(
+            'custom-icons',
+            'gitbook',
+            'gb-icon-custom-icons-gitbook'
+        );
+        const sharp = await getIconSymbol(
+            'sharp-solid',
+            'download',
+            'gb-icon-sharp-solid-download'
+        );
+
+        expect(regular?.symbol).toContain('id="gb-icon-regular-jar"');
+        expect(regular?.symbol).toContain('viewBox="0 0 320 512"');
+        expect(brand?.symbol).toContain('id="gb-icon-brands-github"');
+        expect(custom?.symbol).toContain('id="gb-icon-custom-icons-gitbook"');
+        expect(sharp?.symbol).toContain('id="gb-icon-sharp-solid-download"');
+    });
+
+    it('emits only the registered subset sprite definitions', async () => {
+        renderToStaticMarkup(
+            <IconsProvider
+                assetsURL="https://icons.example.test"
+                iconStyle={IconStyle.Regular}
+                renderMode="symbol"
+                symbolLoaderURL="/~gitbook/icons/symbol"
+            >
+                <>
+                    <Icon icon="jar" iconStyle={IconStyle.Regular} />
+                    <Icon icon="jar" iconStyle={IconStyle.Regular} />
+                    <Icon icon="github" />
+                    <Icon icon="download" iconStyle={IconStyle.SharpSolid} />
+                    <Icon icon="gitbook" />
+                </>
+            </IconsProvider>
+        );
+
+        const sprite = await IconSpriteDefinitions();
+        const html = sprite ? renderToStaticMarkup(sprite) : '';
+
+        expect(html).toContain('data-testid="icon-sprite-root"');
+        expect(html).toContain('id="gb-icon-regular-jar"');
+        expect(html).toContain('id="gb-icon-brands-github"');
+        expect(html).toContain('id="gb-icon-sharp-solid-download"');
+        expect(html).toContain('id="gb-icon-custom-icons-gitbook"');
+        expect(html.match(/id="gb-icon-regular-jar"/g)?.length).toBe(1);
+    });
+
+    it('eagerly seeds search chrome icons into the sprite', async () => {
+        const sprite = await IconSpriteDefinitions();
+        const html = sprite ? renderToStaticMarkup(sprite) : '';
+
+        expect(html).toContain('id="gb-icon-regular-search"');
+        expect(html).toContain('id="gb-icon-regular-chevron-right"');
+        expect(html).toContain('id="gb-icon-regular-arrow-turn-down-left"');
+        expect(html).toContain('id="gb-icon-regular-xmark"');
+    });
+
+    it('serves symbols from the internal route', async () => {
+        const response = await GET(
+            new Request(
+                'http://localhost/~gitbook/icons/symbol/brands/github'
+            ) as unknown as NextRequest,
+            {
+                params: Promise.resolve({
+                    style: 'brands',
+                    icon: 'github',
+                }),
+            }
+        );
+
+        expect(response.status).toBe(200);
+        expect(response.headers.get('content-type')).toBe('image/svg+xml; charset=utf-8');
+        expect(await response.text()).toContain('id="gb-icon-brands-github"');
+    });
+
+    it('serves alias-based symbols from the internal route', async () => {
+        const response = await GET(
+            new Request(
+                'http://localhost/~gitbook/icons/symbol/regular/search'
+            ) as unknown as NextRequest,
+            {
+                params: Promise.resolve({
+                    style: 'regular',
+                    icon: 'search',
+                }),
+            }
+        );
+
+        expect(response.status).toBe(200);
+        expect(await response.text()).toContain('id="gb-icon-regular-search"');
+    });
+});
diff --git a/packages/gitbook/src/lib/icons/symbols.ts b/packages/gitbook/src/lib/icons/symbols.ts
new file mode 100644
index 0000000000..75a567c31f
--- /dev/null
+++ b/packages/gitbook/src/lib/icons/symbols.ts
@@ -0,0 +1,81 @@
+import 'server-only';
+
+import type { StyleIconSymbolManifest } from './types';
+
+const loaders = {
+    brands: () =>
+        import('../../../.generated/icon-symbols/brands.json', { with: { type: 'json' } }),
+    'custom-icons': () =>
+        import('../../../.generated/icon-symbols/custom-icons.json', {
+            with: { type: 'json' },
+        }),
+    duotone: () =>
+        import('../../../.generated/icon-symbols/duotone.json', { with: { type: 'json' } }),
+    light: () => import('../../../.generated/icon-symbols/light.json', { with: { type: 'json' } }),
+    regular: () =>
+        import('../../../.generated/icon-symbols/regular.json', { with: { type: 'json' } }),
+    'sharp-duotone-solid': () =>
+        import('../../../.generated/icon-symbols/sharp-duotone-solid.json', {
+            with: { type: 'json' },
+        }),
+    'sharp-light': () =>
+        import('../../../.generated/icon-symbols/sharp-light.json', { with: { type: 'json' } }),
+    'sharp-regular': () =>
+        import('../../../.generated/icon-symbols/sharp-regular.json', {
+            with: { type: 'json' },
+        }),
+    'sharp-solid': () =>
+        import('../../../.generated/icon-symbols/sharp-solid.json', { with: { type: 'json' } }),
+    'sharp-thin': () =>
+        import('../../../.generated/icon-symbols/sharp-thin.json', { with: { type: 'json' } }),
+    solid: () => import('../../../.generated/icon-symbols/solid.json', { with: { type: 'json' } }),
+    thin: () => import('../../../.generated/icon-symbols/thin.json', { with: { type: 'json' } }),
+} satisfies Record<string, () => Promise<{ default: StyleIconSymbolManifest }>>;
+
+type SupportedSymbolStyle = keyof typeof loaders;
+
+const manifestPromises = new Map<string, Promise<StyleIconSymbolManifest>>();
+
+function escapeAttribute(value: string): string {
+    return value
+        .replaceAll('&', '&amp;')
+        .replaceAll('"', '&quot;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;');
+}
+
+export async function getIconStyleManifest(style: string): Promise<StyleIconSymbolManifest | null> {
+    const load = loaders[style as SupportedSymbolStyle];
+    if (!load) {
+        return null;
+    }
+
+    const existing = manifestPromises.get(style);
+    if (existing) {
+        return existing;
+    }
+
+    const manifestPromise: Promise<StyleIconSymbolManifest> = load().then(
+        (module) => module.default
+    );
+    manifestPromises.set(style, manifestPromise);
+
+    return manifestPromise;
+}
+
+export async function getIconSymbol(style: string, icon: string, symbolId: string) {
+    const manifest = await getIconStyleManifest(style);
+    const entry = manifest?.[icon];
+    if (!entry) {
+        return null;
+    }
+
+    return {
+        style,
+        icon,
+        symbolId,
+        viewBox: entry.viewBox,
+        markup: entry.markup,
+        symbol: `<symbol id="${escapeAttribute(symbolId)}" viewBox="${escapeAttribute(entry.viewBox)}" overflow="visible">${entry.markup}</symbol>`,
+    };
+}
diff --git a/packages/gitbook/src/lib/icons/types.ts b/packages/gitbook/src/lib/icons/types.ts
new file mode 100644
index 0000000000..de220e0a15
--- /dev/null
+++ b/packages/gitbook/src/lib/icons/types.ts
@@ -0,0 +1,6 @@
+export interface StyleIconSymbolManifestEntry {
+    viewBox: string;
+    markup: string;
+}
+
+export type StyleIconSymbolManifest = Record<string, StyleIconSymbolManifestEntry>;
diff --git a/packages/icons/src/Icon.test.tsx b/packages/icons/src/Icon.test.tsx
new file mode 100644
index 0000000000..a91acb2887
--- /dev/null
+++ b/packages/icons/src/Icon.test.tsx
@@ -0,0 +1,63 @@
+import { afterEach, describe, expect, it } from 'bun:test';
+import { renderToStaticMarkup } from 'react-dom/server';
+
+import { Icon } from './Icon';
+import { IconsProvider } from './IconsProvider';
+import { clearRegisteredServerIconSymbols, getRegisteredServerIconSymbols } from './symbols';
+import { IconStyle } from './types';
+
+afterEach(() => {
+    clearRegisteredServerIconSymbols();
+});
+
+function RegisteredSymbolsSummary() {
+    const symbols = getRegisteredServerIconSymbols();
+    return (
+        <output
+            data-testid="registered-symbols"
+            data-count={symbols.length}
+            data-symbol-ids={symbols.map((symbol) => symbol.symbolId).join(',')}
+        />
+    );
+}
+
+describe('Icon', () => {
+    it('renders the mask-image path when symbol mode is disabled', () => {
+        const html = renderToStaticMarkup(
+            <IconsProvider assetsURL="https://icons.example.test" iconStyle={IconStyle.Regular}>
+                <Icon icon="github" className="size-4" />
+            </IconsProvider>
+        );
+
+        expect(html).toContain('data-testid="mask-image"');
+        expect(html).toContain('https://icons.example.test/svgs/brands/github.svg?v=2');
+        expect(html).not.toContain('data-testid="symbol-use"');
+    });
+
+    it('renders inline symbol references and deduplicates SSR registrations', () => {
+        const html = renderToStaticMarkup(
+            <IconsProvider
+                assetsURL="https://icons.example.test"
+                iconStyle={IconStyle.Regular}
+                renderMode="symbol"
+                symbolLoaderURL="/~gitbook/icons/symbol"
+            >
+                <>
+                    <Icon icon="github" />
+                    <Icon icon="github" />
+                    <Icon icon="gitbook" />
+                    <RegisteredSymbolsSummary />
+                </>
+            </IconsProvider>
+        );
+
+        expect(html).toContain('data-testid="symbol-use"');
+        expect(html).toContain('href="#gb-icon-brands-github"');
+        expect(html).toContain('href="#gb-icon-custom-icons-gitbook"');
+        expect(html).toContain('data-testid="registered-symbols"');
+        expect(html).toContain('data-count="2"');
+        expect(html).toContain(
+            'data-symbol-ids="gb-icon-brands-github,gb-icon-custom-icons-gitbook"'
+        );
+    });
+});
diff --git a/packages/icons/src/Icon.tsx b/packages/icons/src/Icon.tsx
index 92e1f7fb47..2d85c1ab3b 100644
--- a/packages/icons/src/Icon.tsx
+++ b/packages/icons/src/Icon.tsx
@@ -2,8 +2,10 @@
 
 import * as React from 'react';
 
+import { IconSymbolLoader } from './IconSymbolLoader';
 import { getIconAssetURL, useIcons } from './IconsProvider';
 import { getIconStyle } from './getIconStyle';
+import { getIconSymbolId, registerServerIconSymbol } from './symbols';
 import type { IconName, IconStyle } from './types';
 
 /**
@@ -50,8 +52,44 @@ export const Icon = React.forwardRef(function Icon(
     } = props;
 
     const [iconStyle, icon] = getIconStyle(propIconStyle, propIcon);
-    const url = getIconAssetURL(context, iconStyle, icon);
     const maskId = React.useId();
+    const iconInstanceId = React.useId();
+    const symbolId = getIconSymbolId(context.symbolIdPrefix, iconStyle, icon);
+
+    if (context.renderMode === 'symbol') {
+        registerServerIconSymbol({
+            style: iconStyle,
+            icon,
+            symbolId,
+        });
+
+        return (
+            <svg
+                ref={ref}
+                {...rest}
+                viewBox="0 0 512 512"
+                data-gb-icon-instance={iconInstanceId}
+                style={{
+                    overflow: 'visible',
+                    ...(size ? { width: size, height: size } : {}),
+                    ...rest.style,
+                }}
+                className={`gb-icon ${className}`}
+            >
+                <title>{icon}</title>
+                <use data-testid="symbol-use" href={`#${symbolId}`} width="100%" height="100%" />
+                {context.symbolLoaderURL ? (
+                    <IconSymbolLoader
+                        instanceId={iconInstanceId}
+                        symbolId={symbolId}
+                        style={iconStyle}
+                        icon={icon}
+                        loaderURL={context.symbolLoaderURL}
+                    />
+                ) : null}
+            </svg>
+        );
+    }
 
     return (
         <svg
@@ -73,7 +111,7 @@ export const Icon = React.forwardRef(function Icon(
                 >
                     <image
                         data-testid="mask-image"
-                        href={url}
+                        href={getIconAssetURL(context, iconStyle, icon)}
                         width="100%"
                         height="100%"
                         preserveAspectRatio="xMidYMid meet"
diff --git a/packages/icons/src/IconSymbolLoader.tsx b/packages/icons/src/IconSymbolLoader.tsx
new file mode 100644
index 0000000000..ebc6981234
--- /dev/null
+++ b/packages/icons/src/IconSymbolLoader.tsx
@@ -0,0 +1,129 @@
+'use client';
+
+import * as React from 'react';
+
+const SVG_NAMESPACE = 'http://www.w3.org/2000/svg';
+const pendingSymbolLoads = new Map<string, Promise<boolean>>();
+
+function createSpriteRoot(): SVGSVGElement {
+    const spriteRoot = document.createElementNS(SVG_NAMESPACE, 'svg');
+    spriteRoot.setAttribute('id', 'gb-icon-sprite-root');
+    spriteRoot.setAttribute('aria-hidden', 'true');
+    spriteRoot.setAttribute('focusable', 'false');
+    spriteRoot.setAttribute(
+        'style',
+        'position:absolute;width:0;height:0;overflow:hidden;pointer-events:none'
+    );
+    document.body.prepend(spriteRoot);
+
+    return spriteRoot;
+}
+
+function getSpriteRoot(): SVGSVGElement {
+    const existing = document.getElementById('gb-icon-sprite-root');
+    if (existing instanceof SVGSVGElement) {
+        return existing;
+    }
+
+    return createSpriteRoot();
+}
+
+function hasSymbol(symbolId: string): boolean {
+    return document.getElementById(symbolId) instanceof SVGElement;
+}
+
+function buildSymbolURL(loaderURL: string, style: string, icon: string): string {
+    const normalizedLoaderURL = loaderURL.endsWith('/') ? loaderURL.slice(0, -1) : loaderURL;
+
+    return `${normalizedLoaderURL}/${encodeURIComponent(style)}/${encodeURIComponent(icon)}`;
+}
+
+async function loadSymbol(symbolId: string, loaderURL: string, style: string, icon: string) {
+    if (hasSymbol(symbolId)) {
+        return true;
+    }
+
+    const cached = pendingSymbolLoads.get(symbolId);
+    if (cached) {
+        return cached;
+    }
+
+    const request = fetch(buildSymbolURL(loaderURL, style, icon), {
+        credentials: 'same-origin',
+    })
+        .then(async (response) => {
+            if (!response.ok) {
+                return false;
+            }
+
+            const symbolMarkup = await response.text();
+            if (hasSymbol(symbolId)) {
+                return true;
+            }
+
+            getSpriteRoot().insertAdjacentHTML('beforeend', symbolMarkup);
+            return hasSymbol(symbolId);
+        })
+        .catch(() => false)
+        .finally(() => {
+            pendingSymbolLoads.delete(symbolId);
+        });
+
+    pendingSymbolLoads.set(symbolId, request);
+    return request;
+}
+
+function setIconFallbackState(instanceId: string, failed: boolean) {
+    const icon = document.querySelector<SVGSVGElement>(
+        `svg[data-gb-icon-instance="${instanceId}"]`
+    );
+    if (!icon) {
+        return;
+    }
+
+    const symbolUse = icon.querySelector<SVGUseElement>('[data-testid="symbol-use"]');
+    const fallback = icon.querySelector<SVGRectElement>('[data-testid="mask-fallback"]');
+
+    if (symbolUse) {
+        symbolUse.style.display = failed ? 'none' : '';
+    }
+
+    if (fallback) {
+        fallback.style.display = failed ? 'block' : 'none';
+    }
+
+    icon.setAttribute('data-gb-icon-symbol-state', failed ? 'failed' : 'loaded');
+}
+
+export function IconSymbolLoader(props: {
+    instanceId: string;
+    symbolId: string;
+    style: string;
+    icon: string;
+    loaderURL: string;
+}) {
+    const { instanceId, symbolId, style, icon, loaderURL } = props;
+
+    React.useEffect(() => {
+        let mounted = true;
+
+        if (hasSymbol(symbolId)) {
+            setIconFallbackState(instanceId, false);
+            return;
+        }
+
+        loadSymbol(symbolId, loaderURL, style, icon).then((loaded) => {
+            if (!mounted) {
+                return;
+            }
+
+            setIconFallbackState(instanceId, !loaded);
+        });
+
+        return () => {
+            mounted = false;
+        };
+    }, [icon, instanceId, loaderURL, style, symbolId]);
+
+    return null;
+}
diff --git a/packages/icons/src/IconsProvider.tsx b/packages/icons/src/IconsProvider.tsx
index 5c5acf5fbf..5d3af7867b 100644
--- a/packages/icons/src/IconsProvider.tsx
+++ b/packages/icons/src/IconsProvider.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import * as React from 'react';
+import type { IconRenderMode } from './symbols';
 import { IconStyle } from './types';
 
 const version = 2;
@@ -17,10 +18,17 @@ export type IconsContextType = Partial<IconsAssetsLocation> & {
     assetsByStyles?: Record<string, IconsAssetsLocation>;
     /** Current default style for icons */
     iconStyle: IconStyle;
+    /** Rendering strategy for icons */
+    renderMode: IconRenderMode;
+    /** Prefix used for inline SVG symbol ids */
+    symbolIdPrefix?: string;
+    /** Internal route used to lazily load symbols introduced after hydration */
+    symbolLoaderURL?: string;
 };
 
 const IconsContext = React.createContext<IconsContextType>({
     iconStyle: IconStyle.Regular,
+    renderMode: 'mask',
 });
 
 /**
@@ -34,10 +42,19 @@ export function IconsProvider(props: React.PropsWithChildren<Partial<IconsContex
         assetsURLToken = parent.assetsURLToken,
         iconStyle = parent.iconStyle,
         assetsByStyles = parent.assetsByStyles,
+        renderMode = parent.renderMode,
+        symbolIdPrefix = parent.symbolIdPrefix,
+        symbolLoaderURL = parent.symbolLoaderURL,
     } = props;
-    const value = React.useMemo(() => {
-        return { assetsURL, assetsURLToken, iconStyle, assetsByStyles };
-    }, [assetsURL, assetsURLToken, iconStyle, assetsByStyles]);
+    const value = {
+        assetsURL,
+        assetsURLToken,
+        iconStyle,
+        assetsByStyles,
+        renderMode,
+        symbolIdPrefix,
+        symbolLoaderURL,
+    };
 
     return <IconsContext.Provider value={value}>{children}</IconsContext.Provider>;
 }
diff --git a/packages/icons/src/index.ts b/packages/icons/src/index.ts
index 8148812a53..f7a775876b 100644
--- a/packages/icons/src/index.ts
+++ b/packages/icons/src/index.ts
@@ -1,3 +1,5 @@
 export * from './Icon';
 export * from './types';
+export * from './symbols';
+export * from './getIconStyle';
 export * from './IconsProvider';
diff --git a/packages/icons/src/symbols.ts b/packages/icons/src/symbols.ts
new file mode 100644
index 0000000000..47f3129a51
--- /dev/null
+++ b/packages/icons/src/symbols.ts
@@ -0,0 +1,53 @@
+export type IconRenderMode = 'mask' | 'symbol';
+
+export interface RegisteredIconSymbol {
+    style: string;
+    icon: string;
+    symbolId: string;
+}
+
+const REGISTERED_SYMBOLS_KEY = Symbol.for('gitbook.icons.registeredSymbols');
+
+function sanitizeSymbolFragment(fragment: string): string {
+    return fragment.replace(/[^a-zA-Z0-9_-]/g, '-');
+}
+
+export function getIconSymbolId(prefix: string | undefined, style: string, icon: string): string {
+    const basePrefix = prefix ?? 'gb-icon-';
+
+    return `${sanitizeSymbolFragment(basePrefix)}${sanitizeSymbolFragment(style)}-${sanitizeSymbolFragment(icon)}`;
+}
+
+function getRegisteredSymbolsStore(): Map<string, RegisteredIconSymbol> {
+    const store = globalThis as typeof globalThis & {
+        [REGISTERED_SYMBOLS_KEY]?: Map<string, RegisteredIconSymbol>;
+    };
+
+    if (!store[REGISTERED_SYMBOLS_KEY]) {
+        store[REGISTERED_SYMBOLS_KEY] = new Map<string, RegisteredIconSymbol>();
+    }
+
+    return store[REGISTERED_SYMBOLS_KEY];
+}
+
+function shouldTrackSymbolRegistrations() {
+    const runtime = globalThis as typeof globalThis & { Bun?: unknown };
+
+    return typeof window === 'undefined' || typeof runtime.Bun !== 'undefined';
+}
+
+export function registerServerIconSymbol(symbol: RegisteredIconSymbol): void {
+    if (!shouldTrackSymbolRegistrations()) {
+        return;
+    }
+
+    getRegisteredSymbolsStore().set(`${symbol.style}/${symbol.icon}`, symbol);
+}
+
+export function getRegisteredServerIconSymbols(): RegisteredIconSymbol[] {
+    return [...getRegisteredSymbolsStore().values()];
+}
+
+export function clearRegisteredServerIconSymbols(): void {
+    getRegisteredSymbolsStore().clear();
+}
diff --git a/packages/icons/tsconfig.json b/packages/icons/tsconfig.json
index 17d6092508..f5a50b8d01 100644
--- a/packages/icons/tsconfig.json
+++ b/packages/icons/tsconfig.json
@@ -1,6 +1,6 @@
 {
     "compilerOptions": {
-        "lib": ["es2023"],
+        "lib": ["es2023", "dom"],
         "module": "ESNext",
         "target": "es2022",
         "strict": true,
diff --git a/turbo.json b/turbo.json
index d9031e75c3..f35d59d56c 100644
--- a/turbo.json
+++ b/turbo.json
@@ -13,7 +13,7 @@
         // Prepare the package for all other tasks
         "generate": {
             "dependsOn": ["^generate"],
-            "outputs": ["dist"]
+            "outputs": ["dist", ".generated/**"]
         },
         // Build the package for publishing
         "build": {

From ab96ee806b4c89547c5c129fbc57a672a92f2cf7 Mon Sep 17 00:00:00 2001
From: Brett Jephson <brett@gitbook.io>
Date: Wed, 29 Apr 2026 17:40:50 +0100
Subject: [PATCH 02/16] changeset

---
 .changeset/olive-bats-yell.md | 6 ++++++
 1 file changed, 6 insertions(+)
 create mode 100644 .changeset/olive-bats-yell.md

diff --git a/.changeset/olive-bats-yell.md b/.changeset/olive-bats-yell.md
new file mode 100644
index 0000000000..df2ac7e9aa
--- /dev/null
+++ b/.changeset/olive-bats-yell.md
@@ -0,0 +1,6 @@
+---
+"@gitbook/icons": minor
+"gitbook": patch
+---
+
+Update icon usage to render svg symbols rather than file.

From c765394914c4ff76bfc7b08a6439bf36175140b5 Mon Sep 17 00:00:00 2001
From: Brett Jephson <brett@gitbook.io>
Date: Wed, 29 Apr 2026 18:02:02 +0100
Subject: [PATCH 03/16] tidy

---
 .../icons/symbol/[style]/[icon]/route.ts      |   2 +-
 .../gitbook/src/lib/icons/symbols.test.tsx    | 110 ------------------
 packages/gitbook/src/lib/icons/symbols.ts     |   5 +-
 packages/icons/src/IconSymbolLoader.tsx       |  25 +++-
 4 files changed, 29 insertions(+), 113 deletions(-)
 delete mode 100644 packages/gitbook/src/lib/icons/symbols.test.tsx

diff --git a/packages/gitbook/src/app/~gitbook/icons/symbol/[style]/[icon]/route.ts b/packages/gitbook/src/app/~gitbook/icons/symbol/[style]/[icon]/route.ts
index 4828323010..39c0e20883 100644
--- a/packages/gitbook/src/app/~gitbook/icons/symbol/[style]/[icon]/route.ts
+++ b/packages/gitbook/src/app/~gitbook/icons/symbol/[style]/[icon]/route.ts
@@ -23,7 +23,7 @@ export async function GET(
         );
     }
 
-    return new NextResponse(symbol.symbol, {
+    return new NextResponse(symbol.document, {
         headers: {
             'content-type': 'image/svg+xml; charset=utf-8',
             'cache-control': 'public, max-age=31536000, immutable',
diff --git a/packages/gitbook/src/lib/icons/symbols.test.tsx b/packages/gitbook/src/lib/icons/symbols.test.tsx
deleted file mode 100644
index 2129c1a271..0000000000
--- a/packages/gitbook/src/lib/icons/symbols.test.tsx
+++ /dev/null
@@ -1,110 +0,0 @@
-import { afterEach, describe, expect, it } from 'bun:test';
-import { Icon, IconStyle, IconsProvider, clearRegisteredServerIconSymbols } from '@gitbook/icons';
-import type { NextRequest } from 'next/server';
-import { renderToStaticMarkup } from 'react-dom/server';
-
-import { GET } from '@/app/~gitbook/icons/symbol/[style]/[icon]/route';
-import { IconSpriteDefinitions } from '@/components/RootLayout/IconSpriteDefinitions';
-
-import { getIconSymbol } from './symbols';
-
-afterEach(() => {
-    clearRegisteredServerIconSymbols();
-});
-
-describe('icon symbols', () => {
-    it('loads symbol markup for multiple families', async () => {
-        const regular = await getIconSymbol('regular', 'jar', 'gb-icon-regular-jar');
-        const brand = await getIconSymbol('brands', 'github', 'gb-icon-brands-github');
-        const custom = await getIconSymbol(
-            'custom-icons',
-            'gitbook',
-            'gb-icon-custom-icons-gitbook'
-        );
-        const sharp = await getIconSymbol(
-            'sharp-solid',
-            'download',
-            'gb-icon-sharp-solid-download'
-        );
-
-        expect(regular?.symbol).toContain('id="gb-icon-regular-jar"');
-        expect(regular?.symbol).toContain('viewBox="0 0 320 512"');
-        expect(brand?.symbol).toContain('id="gb-icon-brands-github"');
-        expect(custom?.symbol).toContain('id="gb-icon-custom-icons-gitbook"');
-        expect(sharp?.symbol).toContain('id="gb-icon-sharp-solid-download"');
-    });
-
-    it('emits only the registered subset sprite definitions', async () => {
-        renderToStaticMarkup(
-            <IconsProvider
-                assetsURL="https://icons.example.test"
-                iconStyle={IconStyle.Regular}
-                renderMode="symbol"
-                symbolLoaderURL="/~gitbook/icons/symbol"
-            >
-                <>
-                    <Icon icon="jar" iconStyle={IconStyle.Regular} />
-                    <Icon icon="jar" iconStyle={IconStyle.Regular} />
-                    <Icon icon="github" />
-                    <Icon icon="download" iconStyle={IconStyle.SharpSolid} />
-                    <Icon icon="gitbook" />
-                </>
-            </IconsProvider>
-        );
-
-        const sprite = await IconSpriteDefinitions();
-        const html = sprite ? renderToStaticMarkup(sprite) : '';
-
-        expect(html).toContain('data-testid="icon-sprite-root"');
-        expect(html).toContain('id="gb-icon-regular-jar"');
-        expect(html).toContain('id="gb-icon-brands-github"');
-        expect(html).toContain('id="gb-icon-sharp-solid-download"');
-        expect(html).toContain('id="gb-icon-custom-icons-gitbook"');
-        expect(html.match(/id="gb-icon-regular-jar"/g)?.length).toBe(1);
-    });
-
-    it('eagerly seeds search chrome icons into the sprite', async () => {
-        const sprite = await IconSpriteDefinitions();
-        const html = sprite ? renderToStaticMarkup(sprite) : '';
-
-        expect(html).toContain('id="gb-icon-regular-search"');
-        expect(html).toContain('id="gb-icon-regular-chevron-right"');
-        expect(html).toContain('id="gb-icon-regular-arrow-turn-down-left"');
-        expect(html).toContain('id="gb-icon-regular-xmark"');
-    });
-
-    it('serves symbols from the internal route', async () => {
-        const response = await GET(
-            new Request(
-                'http://localhost/~gitbook/icons/symbol/brands/github'
-            ) as unknown as NextRequest,
-            {
-                params: Promise.resolve({
-                    style: 'brands',
-                    icon: 'github',
-                }),
-            }
-        );
-
-        expect(response.status).toBe(200);
-        expect(response.headers.get('content-type')).toBe('image/svg+xml; charset=utf-8');
-        expect(await response.text()).toContain('id="gb-icon-brands-github"');
-    });
-
-    it('serves alias-based symbols from the internal route', async () => {
-        const response = await GET(
-            new Request(
-                'http://localhost/~gitbook/icons/symbol/regular/search'
-            ) as unknown as NextRequest,
-            {
-                params: Promise.resolve({
-                    style: 'regular',
-                    icon: 'search',
-                }),
-            }
-        );
-
-        expect(response.status).toBe(200);
-        expect(await response.text()).toContain('id="gb-icon-regular-search"');
-    });
-});
diff --git a/packages/gitbook/src/lib/icons/symbols.ts b/packages/gitbook/src/lib/icons/symbols.ts
index 75a567c31f..92c5aaae39 100644
--- a/packages/gitbook/src/lib/icons/symbols.ts
+++ b/packages/gitbook/src/lib/icons/symbols.ts
@@ -70,12 +70,15 @@ export async function getIconSymbol(style: string, icon: string, symbolId: strin
         return null;
     }
 
+    const symbol = `<symbol id="${escapeAttribute(symbolId)}" viewBox="${escapeAttribute(entry.viewBox)}" overflow="visible">${entry.markup}</symbol>`;
+
     return {
         style,
         icon,
         symbolId,
         viewBox: entry.viewBox,
         markup: entry.markup,
-        symbol: `<symbol id="${escapeAttribute(symbolId)}" viewBox="${escapeAttribute(entry.viewBox)}" overflow="visible">${entry.markup}</symbol>`,
+        symbol,
+        document: `<svg xmlns="http://www.w3.org/2000/svg"><defs>${symbol}</defs><use href="#${escapeAttribute(symbolId)}"/></svg>`,
     };
 }
diff --git a/packages/icons/src/IconSymbolLoader.tsx b/packages/icons/src/IconSymbolLoader.tsx
index ebc6981234..e11453ee53 100644
--- a/packages/icons/src/IconSymbolLoader.tsx
+++ b/packages/icons/src/IconSymbolLoader.tsx
@@ -38,6 +38,26 @@ function buildSymbolURL(loaderURL: string, style: string, icon: string): string
     return `${normalizedLoaderURL}/${encodeURIComponent(style)}/${encodeURIComponent(icon)}`;
 }
 
+function appendSymbolsFromDocument(markup: string): boolean {
+    const parsed = new DOMParser().parseFromString(markup, 'image/svg+xml');
+    const symbols = Array.from(parsed.querySelectorAll('symbol'));
+    if (symbols.length === 0) {
+        return false;
+    }
+
+    const spriteRoot = getSpriteRoot();
+    for (const symbol of symbols) {
+        const symbolId = symbol.getAttribute('id');
+        if (!symbolId || hasSymbol(symbolId)) {
+            continue;
+        }
+
+        spriteRoot.appendChild(document.importNode(symbol, true));
+    }
+
+    return true;
+}
+
 async function loadSymbol(symbolId: string, loaderURL: string, style: string, icon: string) {
     if (hasSymbol(symbolId)) {
         return true;
@@ -61,7 +81,10 @@ async function loadSymbol(symbolId: string, loaderURL: string, style: string, ic
                 return true;
             }
 
-            getSpriteRoot().insertAdjacentHTML('beforeend', symbolMarkup);
+            if (!appendSymbolsFromDocument(symbolMarkup)) {
+                return false;
+            }
+
             return hasSymbol(symbolId);
         })
         .catch(() => false)

From 07be0e224c351264094fdf783a1685a67563aa6c Mon Sep 17 00:00:00 2001
From: Brett Jephson <brett@gitbook.io>
Date: Thu, 30 Apr 2026 09:41:57 +0100
Subject: [PATCH 04/16] use shared supported style info

---
 .../gitbook/scripts/generate-icon-symbols.js  | 35 +++++++++++--------
 .../src/lib/icons/supported-styles.json       | 14 ++++++++
 packages/gitbook/src/lib/icons/symbols.ts     | 33 ++---------------
 3 files changed, 36 insertions(+), 46 deletions(-)
 create mode 100644 packages/gitbook/src/lib/icons/supported-styles.json

diff --git a/packages/gitbook/scripts/generate-icon-symbols.js b/packages/gitbook/scripts/generate-icon-symbols.js
index fb5127d955..ed1c7b250e 100644
--- a/packages/gitbook/scripts/generate-icon-symbols.js
+++ b/packages/gitbook/scripts/generate-icon-symbols.js
@@ -5,26 +5,29 @@ const path = require('node:path');
 
 const packageJSONPath = require.resolve('@gitbook/fontawesome-pro/package.json');
 const packageRoot = path.dirname(packageJSONPath);
+const supportedStyles = require('../src/lib/icons/supported-styles.json');
 const outputDirectory = path.resolve(__dirname, '../.generated/icon-symbols');
+const loadersModulePath = path.resolve(__dirname, '../.generated/icon-symbol-loaders.ts');
 const metadataPath = path.join(packageRoot, 'icons', 'metadata', 'icons.json');
 
-const supportedStyles = [
-    'brands',
-    'custom-icons',
-    'duotone',
-    'light',
-    'regular',
-    'sharp-duotone-solid',
-    'sharp-light',
-    'sharp-regular',
-    'sharp-solid',
-    'sharp-thin',
-    'solid',
-    'thin',
-];
-
 const symbolPattern = /<symbol id="([^"]+)" viewBox="([^"]+)">([\s\S]*?)<\/symbol>/g;
 
+function generateLoadersModule(styles) {
+    const entries = styles
+        .map((style) => {
+            return `    ${JSON.stringify(style)}: () =>
+        import('./icon-symbols/${style}.json', { with: { type: 'json' } }),`;
+        })
+        .join('\n');
+
+    return `import type { StyleIconSymbolManifest } from '../src/lib/icons/types';
+
+export const loaders = {
+${entries}
+} satisfies Record<string, () => Promise<{ default: StyleIconSymbolManifest }>>;
+`;
+}
+
 async function main() {
     await fs.rm(outputDirectory, { recursive: true, force: true });
     await fs.mkdir(outputDirectory, { recursive: true });
@@ -63,6 +66,8 @@ async function main() {
         })
     );
 
+    await fs.writeFile(loadersModulePath, generateLoadersModule(supportedStyles), 'utf8');
+
     // biome-ignore lint/suspicious/noConsole: CLI output is useful when regenerating manifests.
     console.log(`Generated ${supportedStyles.length} icon symbol manifests in ${outputDirectory}`);
 }
diff --git a/packages/gitbook/src/lib/icons/supported-styles.json b/packages/gitbook/src/lib/icons/supported-styles.json
new file mode 100644
index 0000000000..38879ea4fe
--- /dev/null
+++ b/packages/gitbook/src/lib/icons/supported-styles.json
@@ -0,0 +1,14 @@
+[
+    "brands",
+    "custom-icons",
+    "duotone",
+    "light",
+    "regular",
+    "sharp-duotone-solid",
+    "sharp-light",
+    "sharp-regular",
+    "sharp-solid",
+    "sharp-thin",
+    "solid",
+    "thin"
+]
diff --git a/packages/gitbook/src/lib/icons/symbols.ts b/packages/gitbook/src/lib/icons/symbols.ts
index 92c5aaae39..d1bb1e04d7 100644
--- a/packages/gitbook/src/lib/icons/symbols.ts
+++ b/packages/gitbook/src/lib/icons/symbols.ts
@@ -1,37 +1,8 @@
 import 'server-only';
 
+import { loaders } from '../../../.generated/icon-symbol-loaders';
 import type { StyleIconSymbolManifest } from './types';
 
-const loaders = {
-    brands: () =>
-        import('../../../.generated/icon-symbols/brands.json', { with: { type: 'json' } }),
-    'custom-icons': () =>
-        import('../../../.generated/icon-symbols/custom-icons.json', {
-            with: { type: 'json' },
-        }),
-    duotone: () =>
-        import('../../../.generated/icon-symbols/duotone.json', { with: { type: 'json' } }),
-    light: () => import('../../../.generated/icon-symbols/light.json', { with: { type: 'json' } }),
-    regular: () =>
-        import('../../../.generated/icon-symbols/regular.json', { with: { type: 'json' } }),
-    'sharp-duotone-solid': () =>
-        import('../../../.generated/icon-symbols/sharp-duotone-solid.json', {
-            with: { type: 'json' },
-        }),
-    'sharp-light': () =>
-        import('../../../.generated/icon-symbols/sharp-light.json', { with: { type: 'json' } }),
-    'sharp-regular': () =>
-        import('../../../.generated/icon-symbols/sharp-regular.json', {
-            with: { type: 'json' },
-        }),
-    'sharp-solid': () =>
-        import('../../../.generated/icon-symbols/sharp-solid.json', { with: { type: 'json' } }),
-    'sharp-thin': () =>
-        import('../../../.generated/icon-symbols/sharp-thin.json', { with: { type: 'json' } }),
-    solid: () => import('../../../.generated/icon-symbols/solid.json', { with: { type: 'json' } }),
-    thin: () => import('../../../.generated/icon-symbols/thin.json', { with: { type: 'json' } }),
-} satisfies Record<string, () => Promise<{ default: StyleIconSymbolManifest }>>;
-
 type SupportedSymbolStyle = keyof typeof loaders;
 
 const manifestPromises = new Map<string, Promise<StyleIconSymbolManifest>>();
@@ -56,7 +27,7 @@ export async function getIconStyleManifest(style: string): Promise<StyleIconSymb
     }
 
     const manifestPromise: Promise<StyleIconSymbolManifest> = load().then(
-        (module) => module.default
+        (module) => module.default as StyleIconSymbolManifest
     );
     manifestPromises.set(style, manifestPromise);
 

From 72cffdd14b1ff2d0b130844d11637d9dfe46c744 Mon Sep 17 00:00:00 2001
From: Brett Jephson <brett@gitbook.io>
Date: Thu, 30 Apr 2026 10:45:25 +0100
Subject: [PATCH 05/16] tidy

---
 packages/gitbook/src/lib/icons/symbols.ts |  7 +++++++
 packages/icons/src/Icon.tsx               |  2 +-
 packages/icons/src/IconSymbolLoader.tsx   |  4 ++++
 packages/icons/src/IconsProvider.tsx      |  4 ----
 packages/icons/src/symbols.ts             | 18 ++++++++++++++----
 5 files changed, 26 insertions(+), 9 deletions(-)

diff --git a/packages/gitbook/src/lib/icons/symbols.ts b/packages/gitbook/src/lib/icons/symbols.ts
index d1bb1e04d7..af514b730b 100644
--- a/packages/gitbook/src/lib/icons/symbols.ts
+++ b/packages/gitbook/src/lib/icons/symbols.ts
@@ -15,6 +15,9 @@ function escapeAttribute(value: string): string {
         .replaceAll('>', '&gt;');
 }
 
+/**
+ * Load and memoize the generated symbol manifest for a Font Awesome style.
+ */
 export async function getIconStyleManifest(style: string): Promise<StyleIconSymbolManifest | null> {
     const load = loaders[style as SupportedSymbolStyle];
     if (!load) {
@@ -34,6 +37,10 @@ export async function getIconStyleManifest(style: string): Promise<StyleIconSymb
     return manifestPromise;
 }
 
+/**
+ * Resolve one icon entry from the generated manifest and serialize it for sprite injection or
+ * lazy-loading through the symbol route.
+ */
 export async function getIconSymbol(style: string, icon: string, symbolId: string) {
     const manifest = await getIconStyleManifest(style);
     const entry = manifest?.[icon];
diff --git a/packages/icons/src/Icon.tsx b/packages/icons/src/Icon.tsx
index 2d85c1ab3b..402c40401e 100644
--- a/packages/icons/src/Icon.tsx
+++ b/packages/icons/src/Icon.tsx
@@ -54,7 +54,7 @@ export const Icon = React.forwardRef(function Icon(
     const [iconStyle, icon] = getIconStyle(propIconStyle, propIcon);
     const maskId = React.useId();
     const iconInstanceId = React.useId();
-    const symbolId = getIconSymbolId(context.symbolIdPrefix, iconStyle, icon);
+    const symbolId = getIconSymbolId(iconStyle, icon);
 
     if (context.renderMode === 'symbol') {
         registerServerIconSymbol({
diff --git a/packages/icons/src/IconSymbolLoader.tsx b/packages/icons/src/IconSymbolLoader.tsx
index e11453ee53..b6675ecf4a 100644
--- a/packages/icons/src/IconSymbolLoader.tsx
+++ b/packages/icons/src/IconSymbolLoader.tsx
@@ -118,6 +118,10 @@ function setIconFallbackState(instanceId: string, failed: boolean) {
     icon.setAttribute('data-gb-icon-symbol-state', failed ? 'failed' : 'loaded');
 }
 
+/**
+ * Ensure a symbol referenced by an inline `<use>` exists after hydration, fetching it from the
+ * internal symbol route only when the SSR sprite did not already include it.
+ */
 export function IconSymbolLoader(props: {
     instanceId: string;
     symbolId: string;
diff --git a/packages/icons/src/IconsProvider.tsx b/packages/icons/src/IconsProvider.tsx
index 5d3af7867b..69cc1c8cc8 100644
--- a/packages/icons/src/IconsProvider.tsx
+++ b/packages/icons/src/IconsProvider.tsx
@@ -20,8 +20,6 @@ export type IconsContextType = Partial<IconsAssetsLocation> & {
     iconStyle: IconStyle;
     /** Rendering strategy for icons */
     renderMode: IconRenderMode;
-    /** Prefix used for inline SVG symbol ids */
-    symbolIdPrefix?: string;
     /** Internal route used to lazily load symbols introduced after hydration */
     symbolLoaderURL?: string;
 };
@@ -43,7 +41,6 @@ export function IconsProvider(props: React.PropsWithChildren<Partial<IconsContex
         iconStyle = parent.iconStyle,
         assetsByStyles = parent.assetsByStyles,
         renderMode = parent.renderMode,
-        symbolIdPrefix = parent.symbolIdPrefix,
         symbolLoaderURL = parent.symbolLoaderURL,
     } = props;
     const value = {
@@ -52,7 +49,6 @@ export function IconsProvider(props: React.PropsWithChildren<Partial<IconsContex
         iconStyle,
         assetsByStyles,
         renderMode,
-        symbolIdPrefix,
         symbolLoaderURL,
     };
 
diff --git a/packages/icons/src/symbols.ts b/packages/icons/src/symbols.ts
index 47f3129a51..4823e85ef8 100644
--- a/packages/icons/src/symbols.ts
+++ b/packages/icons/src/symbols.ts
@@ -12,10 +12,11 @@ function sanitizeSymbolFragment(fragment: string): string {
     return fragment.replace(/[^a-zA-Z0-9_-]/g, '-');
 }
 
-export function getIconSymbolId(prefix: string | undefined, style: string, icon: string): string {
-    const basePrefix = prefix ?? 'gb-icon-';
-
-    return `${sanitizeSymbolFragment(basePrefix)}${sanitizeSymbolFragment(style)}-${sanitizeSymbolFragment(icon)}`;
+/**
+ * Build the DOM id used by both SSR-emitted symbols and the lazy symbol loader.
+ */
+export function getIconSymbolId(style: string, icon: string): string {
+    return `gb-icon-${sanitizeSymbolFragment(style)}-${sanitizeSymbolFragment(icon)}`;
 }
 
 function getRegisteredSymbolsStore(): Map<string, RegisteredIconSymbol> {
@@ -36,6 +37,9 @@ function shouldTrackSymbolRegistrations() {
     return typeof window === 'undefined' || typeof runtime.Bun !== 'undefined';
 }
 
+/**
+ * Record a symbol used during server rendering so the app can emit a deduplicated sprite subset.
+ */
 export function registerServerIconSymbol(symbol: RegisteredIconSymbol): void {
     if (!shouldTrackSymbolRegistrations()) {
         return;
@@ -44,10 +48,16 @@ export function registerServerIconSymbol(symbol: RegisteredIconSymbol): void {
     getRegisteredSymbolsStore().set(`${symbol.style}/${symbol.icon}`, symbol);
 }
 
+/**
+ * Return the currently registered server-rendered symbols in insertion order.
+ */
 export function getRegisteredServerIconSymbols(): RegisteredIconSymbol[] {
     return [...getRegisteredSymbolsStore().values()];
 }
 
+/**
+ * Reset the per-request symbol registry after the sprite subset has been emitted.
+ */
 export function clearRegisteredServerIconSymbols(): void {
     getRegisteredSymbolsStore().clear();
 }

From 568ee3a660555af576c7fb21aed20e7c75f87918 Mon Sep 17 00:00:00 2001
From: Brett Jephson <brett@gitbook.io>
Date: Thu, 30 Apr 2026 11:31:00 +0100
Subject: [PATCH 06/16] tidy and update icon loading in test

---
 packages/gitbook/e2e/util.ts            |   5 ++
 packages/icons/src/IconSymbolLoader.tsx | 111 ++++++++++++------------
 2 files changed, 60 insertions(+), 56 deletions(-)

diff --git a/packages/gitbook/e2e/util.ts b/packages/gitbook/e2e/util.ts
index 1248d53a65..607e538077 100644
--- a/packages/gitbook/e2e/util.ts
+++ b/packages/gitbook/e2e/util.ts
@@ -443,6 +443,11 @@ export async function waitForIcons(page: Page) {
                 return true;
             }
 
+            const svgSymbol = icon.querySelector('[data-testid="symbol-use"]');
+            if (svgSymbol) {
+                return icon.dataset.gbIIconSymbolState === 'loaded';
+            }
+
             const maskImage = icon.querySelector('[data-testid="mask-image"]');
             if (!maskImage) {
                 throw new Error('No mask-image element');
diff --git a/packages/icons/src/IconSymbolLoader.tsx b/packages/icons/src/IconSymbolLoader.tsx
index b6675ecf4a..c1c8720c3e 100644
--- a/packages/icons/src/IconSymbolLoader.tsx
+++ b/packages/icons/src/IconSymbolLoader.tsx
@@ -5,6 +5,58 @@ import * as React from 'react';
 const SVG_NAMESPACE = 'http://www.w3.org/2000/svg';
 const pendingSymbolLoads = new Map<string, Promise<boolean>>();
 
+/**
+ * Ensure a symbol referenced by an inline `<use>` exists after hydration, fetching it from the
+ * internal symbol route only when the SSR sprite did not already include it.
+ */
+export function IconSymbolLoader(props: {
+    instanceId: string;
+    symbolId: string;
+    style: string;
+    icon: string;
+    loaderURL: string;
+}) {
+    const { instanceId, symbolId, style, icon, loaderURL } = props;
+
+    React.useEffect(() => {
+        let mounted = true;
+
+        if (hasSymbol(symbolId)) {
+            setIconState(instanceId, true);
+            return;
+        }
+
+        loadSymbol(symbolId, loaderURL, style, icon).then((loaded) => {
+            if (!mounted) {
+                return;
+            }
+
+            setIconState(instanceId, loaded);
+        });
+
+        return () => {
+            mounted = false;
+        };
+    }, [icon, instanceId, loaderURL, style, symbolId]);
+
+    return null;
+}
+
+/**
+ * A root SVG element used to host the loaded symbols as a spritesheet. This is used as a reference point for the `<use>` elements in the icons.
+ */
+function getSpriteRoot(): SVGSVGElement {
+    const existing = document.getElementById('gb-icon-sprite-root');
+    if (existing instanceof SVGSVGElement) {
+        return existing;
+    }
+
+    return createSpriteRoot();
+}
+
+/**
+ * Creates the root SVG element for the spritesheet if it doesn't already exist, and appends it to the document body.
+ */
 function createSpriteRoot(): SVGSVGElement {
     const spriteRoot = document.createElementNS(SVG_NAMESPACE, 'svg');
     spriteRoot.setAttribute('id', 'gb-icon-sprite-root');
@@ -19,15 +71,6 @@ function createSpriteRoot(): SVGSVGElement {
     return spriteRoot;
 }
 
-function getSpriteRoot(): SVGSVGElement {
-    const existing = document.getElementById('gb-icon-sprite-root');
-    if (existing instanceof SVGSVGElement) {
-        return existing;
-    }
-
-    return createSpriteRoot();
-}
-
 function hasSymbol(symbolId: string): boolean {
     return document.getElementById(symbolId) instanceof SVGElement;
 }
@@ -96,7 +139,7 @@ async function loadSymbol(symbolId: string, loaderURL: string, style: string, ic
     return request;
 }
 
-function setIconFallbackState(instanceId: string, failed: boolean) {
+function setIconState(instanceId: string, loaded: boolean) {
     const icon = document.querySelector<SVGSVGElement>(
         `svg[data-gb-icon-instance="${instanceId}"]`
     );
@@ -105,52 +148,8 @@ function setIconFallbackState(instanceId: string, failed: boolean) {
     }
 
     const symbolUse = icon.querySelector<SVGUseElement>('[data-testid="symbol-use"]');
-    const fallback = icon.querySelector<SVGRectElement>('[data-testid="mask-fallback"]');
-
     if (symbolUse) {
-        symbolUse.style.display = failed ? 'none' : '';
-    }
-
-    if (fallback) {
-        fallback.style.display = failed ? 'block' : 'none';
+        symbolUse.style.display = loaded ? '' : 'none';
     }
-
-    icon.setAttribute('data-gb-icon-symbol-state', failed ? 'failed' : 'loaded');
-}
-
-/**
- * Ensure a symbol referenced by an inline `<use>` exists after hydration, fetching it from the
- * internal symbol route only when the SSR sprite did not already include it.
- */
-export function IconSymbolLoader(props: {
-    instanceId: string;
-    symbolId: string;
-    style: string;
-    icon: string;
-    loaderURL: string;
-}) {
-    const { instanceId, symbolId, style, icon, loaderURL } = props;
-
-    React.useEffect(() => {
-        let mounted = true;
-
-        if (hasSymbol(symbolId)) {
-            setIconFallbackState(instanceId, false);
-            return;
-        }
-
-        loadSymbol(symbolId, loaderURL, style, icon).then((loaded) => {
-            if (!mounted) {
-                return;
-            }
-
-            setIconFallbackState(instanceId, !loaded);
-        });
-
-        return () => {
-            mounted = false;
-        };
-    }, [icon, instanceId, loaderURL, style, symbolId]);
-
-    return null;
+    icon.setAttribute('data-gb-icon-symbol-state', loaded ? 'loaded' : 'failed');
 }

From 2746ffc000e40ed4ba5661809713754bf5eb05b9 Mon Sep 17 00:00:00 2001
From: Brett Jephson <brett@gitbook.io>
Date: Thu, 30 Apr 2026 12:01:53 +0100
Subject: [PATCH 07/16] test fix

---
 packages/gitbook/e2e/util.ts | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/gitbook/e2e/util.ts b/packages/gitbook/e2e/util.ts
index 607e538077..15d8bb99a6 100644
--- a/packages/gitbook/e2e/util.ts
+++ b/packages/gitbook/e2e/util.ts
@@ -433,6 +433,11 @@ export async function waitForIcons(page: Page) {
                 return true;
             }
 
+            const svgSymbol = icon.querySelector('[data-testid="symbol-use"]');
+            if (svgSymbol) {
+                return icon.dataset.gbIIconSymbolState === 'loaded';
+            }
+
             const state = icon.getAttribute('data-argos-state');
 
             if (state === 'pending') {
@@ -443,11 +448,6 @@ export async function waitForIcons(page: Page) {
                 return true;
             }
 
-            const svgSymbol = icon.querySelector('[data-testid="symbol-use"]');
-            if (svgSymbol) {
-                return icon.dataset.gbIIconSymbolState === 'loaded';
-            }
-
             const maskImage = icon.querySelector('[data-testid="mask-image"]');
             if (!maskImage) {
                 throw new Error('No mask-image element');

From 21053f56fbfc13eeabe85b5e4c963308f2ee05c4 Mon Sep 17 00:00:00 2001
From: Brett Jephson <brett@gitbook.io>
Date: Thu, 30 Apr 2026 13:47:16 +0100
Subject: [PATCH 08/16] Update method of loading symbols

---
 packages/gitbook/.gitignore                   |   1 -
 packages/gitbook/package.json                 |   2 +-
 .../gitbook/scripts/generate-icon-symbols.js  | 136 ++++++++++++------
 .../icons/symbol/[style]/[icon]/route.ts      |  32 -----
 .../RootLayout/CustomizationRootLayout.tsx    |   2 +-
 packages/gitbook/src/lib/icons/symbols.ts     | 132 ++++++++++++++---
 packages/gitbook/src/lib/icons/types.ts       |   6 -
 packages/icons/src/Icon.test.tsx              |   2 +-
 packages/icons/src/IconSymbolLoader.tsx       |   6 +-
 packages/icons/src/IconsProvider.tsx          |   2 +-
 10 files changed, 212 insertions(+), 109 deletions(-)
 delete mode 100644 packages/gitbook/src/app/~gitbook/icons/symbol/[style]/[icon]/route.ts
 delete mode 100644 packages/gitbook/src/lib/icons/types.ts

diff --git a/packages/gitbook/.gitignore b/packages/gitbook/.gitignore
index f8c2962787..9dc62697e7 100644
--- a/packages/gitbook/.gitignore
+++ b/packages/gitbook/.gitignore
@@ -32,7 +32,6 @@ screenshots/
 # Generated public files
 /public/~gitbook/static/*
 !/public/~gitbook/static/images
-/.generated/
 
 # cloudflare
 .open-next
diff --git a/packages/gitbook/package.json b/packages/gitbook/package.json
index 9088261887..56840a2cb4 100644
--- a/packages/gitbook/package.json
+++ b/packages/gitbook/package.json
@@ -120,7 +120,7 @@
     "scripts": {
         "generate:icon-symbols": "node ./scripts/generate-icon-symbols.js",
         "generate": "./scripts/generate.sh",
-        "clean": "rm -rf ./.next && rm -rf ./.generated && rm -rf ./public/~gitbook/static/icons && rm -rf ./public/~gitbook/static/math",
+        "clean": "rm -rf ./.next && rm -rf ./public/~gitbook/static/icon-symbols && rm -rf ./public/~gitbook/static/icons && rm -rf ./public/~gitbook/static/math",
         "dev": "env-cmd --silent -f ../../.env.local next --webpack",
         "build": "next build --webpack",
         "build:local": "GITBOOK_URL=http://localhost:3000 next build --webpack",
diff --git a/packages/gitbook/scripts/generate-icon-symbols.js b/packages/gitbook/scripts/generate-icon-symbols.js
index ed1c7b250e..41073cf94f 100644
--- a/packages/gitbook/scripts/generate-icon-symbols.js
+++ b/packages/gitbook/scripts/generate-icon-symbols.js
@@ -6,26 +6,44 @@ const path = require('node:path');
 const packageJSONPath = require.resolve('@gitbook/fontawesome-pro/package.json');
 const packageRoot = path.dirname(packageJSONPath);
 const supportedStyles = require('../src/lib/icons/supported-styles.json');
-const outputDirectory = path.resolve(__dirname, '../.generated/icon-symbols');
-const loadersModulePath = path.resolve(__dirname, '../.generated/icon-symbol-loaders.ts');
+const outputDirectory = path.resolve(__dirname, '../public/~gitbook/static/icon-symbols');
 const metadataPath = path.join(packageRoot, 'icons', 'metadata', 'icons.json');
 
+const svgPattern = /<svg\b([^>]*)>([\s\S]*?)<\/svg>\s*$/i;
 const symbolPattern = /<symbol id="([^"]+)" viewBox="([^"]+)">([\s\S]*?)<\/symbol>/g;
+const viewBoxPattern = /\bviewBox="([^"]+)"/i;
+const commentPattern = /<!--[\s\S]*?-->/g;
 
-function generateLoadersModule(styles) {
-    const entries = styles
-        .map((style) => {
-            return `    ${JSON.stringify(style)}: () =>
-        import('./icon-symbols/${style}.json', { with: { type: 'json' } }),`;
-        })
-        .join('\n');
+function sanitizeSymbolFragment(fragment) {
+    return fragment.replace(/[^a-zA-Z0-9_-]/g, '-');
+}
+
+function getSymbolId(style, icon) {
+    return `gb-icon-${sanitizeSymbolFragment(style)}-${sanitizeSymbolFragment(icon)}`;
+}
+
+function buildSymbolDocumentFromSource(style, icon, source) {
+    const symbolId = getSymbolId(style, icon);
+
+    return `<svg xmlns="http://www.w3.org/2000/svg"><defs><symbol id="${symbolId}" viewBox="${source.viewBox}" overflow="visible">${source.markup}</symbol></defs><use href="#${symbolId}"/></svg>`;
+}
 
-    return `import type { StyleIconSymbolManifest } from '../src/lib/icons/types';
+function getSymbolSourceFromSVG(svgMarkup, style, icon) {
+    const svgMatch = svgMarkup.match(svgPattern);
+    if (!svgMatch) {
+        throw new Error(`Invalid SVG source for "${style}/${icon}"`);
+    }
 
-export const loaders = {
-${entries}
-} satisfies Record<string, () => Promise<{ default: StyleIconSymbolManifest }>>;
-`;
+    const [, svgAttributes, innerMarkup] = svgMatch;
+    const viewBoxMatch = svgAttributes.match(viewBoxPattern);
+    if (!viewBoxMatch) {
+        throw new Error(`Missing viewBox for "${style}/${icon}"`);
+    }
+
+    return {
+        viewBox: viewBoxMatch[1],
+        markup: innerMarkup.replace(commentPattern, '').trim(),
+    };
 }
 
 async function main() {
@@ -35,41 +53,79 @@ async function main() {
 
     await Promise.all(
         supportedStyles.map(async (style) => {
+            const stylePath = path.join(packageRoot, 'icons', 'svgs', style);
             const spritePath = path.join(packageRoot, 'icons', 'sprites', `${style}.svg`);
-            if (!existsSync(spritePath)) {
-                throw new Error(`Missing sprite file for "${style}": ${spritePath}`);
+            if (!existsSync(stylePath)) {
+                if (!existsSync(spritePath)) {
+                    throw new Error(
+                        `Missing SVG directory and sprite file for "${style}": ${stylePath}, ${spritePath}`
+                    );
+                }
             }
 
-            const sprite = await fs.readFile(spritePath, 'utf8');
-            const entries = {};
-
-            for (const match of sprite.matchAll(symbolPattern)) {
-                const [, icon, viewBox, markup] = match;
-                entries[icon] = {
-                    viewBox,
-                    markup,
-                };
-
-                const aliases = iconMetadata[icon]?.aliases?.names ?? [];
-                for (const alias of aliases) {
-                    if (!entries[alias]) {
-                        entries[alias] = entries[icon];
-                    }
-                }
+            const styleOutputDirectory = path.join(outputDirectory, style);
+            await fs.mkdir(styleOutputDirectory, { recursive: true });
+            const generatedIcons = new Map();
+
+            if (existsSync(stylePath)) {
+                const sourceFiles = await fs.readdir(stylePath, { withFileTypes: true });
+                await Promise.all(
+                    sourceFiles
+                        .filter((entry) => entry.isFile() && entry.name.endsWith('.svg'))
+                        .map(async (entry) => {
+                            const sourcePath = path.join(stylePath, entry.name);
+                            const icon = path.basename(entry.name, '.svg');
+                            const svgMarkup = await fs.readFile(sourcePath, 'utf8');
+                            const symbolSource = getSymbolSourceFromSVG(svgMarkup, style, icon);
+
+                            generatedIcons.set(icon, symbolSource);
+                            await fs.writeFile(
+                                path.join(styleOutputDirectory, entry.name),
+                                buildSymbolDocumentFromSource(style, icon, symbolSource),
+                                'utf8'
+                            );
+                        })
+                );
+            } else {
+                const sprite = await fs.readFile(spritePath, 'utf8');
+                await Promise.all(
+                    [...sprite.matchAll(symbolPattern)].map(async (match) => {
+                        const [, icon, viewBox, markup] = match;
+                        const symbolSource = {
+                            viewBox,
+                            markup: markup.replace(commentPattern, '').trim(),
+                        };
+
+                        generatedIcons.set(icon, symbolSource);
+                        await fs.writeFile(
+                            path.join(styleOutputDirectory, `${icon}.svg`),
+                            buildSymbolDocumentFromSource(style, icon, symbolSource),
+                            'utf8'
+                        );
+                    })
+                );
             }
 
-            await fs.writeFile(
-                path.join(outputDirectory, `${style}.json`),
-                JSON.stringify(entries),
-                'utf8'
+            await Promise.all(
+                [...generatedIcons.entries()].flatMap(([icon, symbolSource]) => {
+                    const aliases = iconMetadata[icon]?.aliases?.names ?? [];
+                    return aliases
+                        .filter((alias) => !generatedIcons.has(alias))
+                        .map(async (alias) => {
+                            generatedIcons.set(alias, symbolSource);
+                            await fs.writeFile(
+                                path.join(styleOutputDirectory, `${alias}.svg`),
+                                buildSymbolDocumentFromSource(style, alias, symbolSource),
+                                'utf8'
+                            );
+                        });
+                })
             );
         })
     );
 
-    await fs.writeFile(loadersModulePath, generateLoadersModule(supportedStyles), 'utf8');
-
-    // biome-ignore lint/suspicious/noConsole: CLI output is useful when regenerating manifests.
-    console.log(`Generated ${supportedStyles.length} icon symbol manifests in ${outputDirectory}`);
+    // biome-ignore lint/suspicious/noConsole: CLI output is useful when regenerating assets.
+    console.log(`Generated symbol SVGs for ${supportedStyles.length} styles in ${outputDirectory}`);
 }
 
 main().catch((error) => {
diff --git a/packages/gitbook/src/app/~gitbook/icons/symbol/[style]/[icon]/route.ts b/packages/gitbook/src/app/~gitbook/icons/symbol/[style]/[icon]/route.ts
deleted file mode 100644
index 39c0e20883..0000000000
--- a/packages/gitbook/src/app/~gitbook/icons/symbol/[style]/[icon]/route.ts
+++ /dev/null
@@ -1,32 +0,0 @@
-import { type NextRequest, NextResponse } from 'next/server';
-
-import { getIconSymbol } from '@/lib/icons/symbols';
-
-function getSymbolId(style: string, icon: string) {
-    const sanitize = (value: string) => value.replace(/[^a-zA-Z0-9_-]/g, '-');
-    return `gb-icon-${sanitize(style)}-${sanitize(icon)}`;
-}
-
-export async function GET(
-    _request: NextRequest,
-    { params }: { params: Promise<{ style: string; icon: string }> }
-) {
-    const { style, icon } = await params;
-    const symbol = await getIconSymbol(style, icon, getSymbolId(style, icon));
-
-    if (!symbol) {
-        return NextResponse.json(
-            {
-                error: 'Symbol not found',
-            },
-            { status: 404 }
-        );
-    }
-
-    return new NextResponse(symbol.document, {
-        headers: {
-            'content-type': 'image/svg+xml; charset=utf-8',
-            'cache-control': 'public, max-age=31536000, immutable',
-        },
-    });
-}
diff --git a/packages/gitbook/src/components/RootLayout/CustomizationRootLayout.tsx b/packages/gitbook/src/components/RootLayout/CustomizationRootLayout.tsx
index 22583c0675..ca2a96e807 100644
--- a/packages/gitbook/src/components/RootLayout/CustomizationRootLayout.tsx
+++ b/packages/gitbook/src/components/RootLayout/CustomizationRootLayout.tsx
@@ -199,7 +199,7 @@ export async function CustomizationRootLayout(props: {
                         },
                     }}
                     renderMode="symbol"
-                    symbolLoaderURL="/~gitbook/icons/symbol"
+                    symbolLoaderURL="/~gitbook/static/icon-symbols"
                     iconStyle={iconStyle}
                 >
                     <RootLayoutClientContexts language={language}>
diff --git a/packages/gitbook/src/lib/icons/symbols.ts b/packages/gitbook/src/lib/icons/symbols.ts
index af514b730b..b2c9fe0e2b 100644
--- a/packages/gitbook/src/lib/icons/symbols.ts
+++ b/packages/gitbook/src/lib/icons/symbols.ts
@@ -1,11 +1,17 @@
 import 'server-only';
 
-import { loaders } from '../../../.generated/icon-symbol-loaders';
-import type { StyleIconSymbolManifest } from './types';
+import { getAssetURL } from '@/lib/assets';
+import { GITBOOK_RUNTIME } from '@/lib/env';
+import { joinPath } from '@/lib/paths';
 
-type SupportedSymbolStyle = keyof typeof loaders;
+interface IconSymbolSource {
+    viewBox: string;
+    markup: string;
+}
 
-const manifestPromises = new Map<string, Promise<StyleIconSymbolManifest>>();
+const symbolSources = new Map<string, Promise<IconSymbolSource | null>>();
+const symbolPattern = /<symbol\b([^>]*)>([\s\S]*?)<\/symbol>/i;
+const viewBoxPattern = /\bviewBox="([^"]+)"/i;
 
 function escapeAttribute(value: string): string {
     return value
@@ -16,47 +22,127 @@ function escapeAttribute(value: string): string {
 }
 
 /**
- * Load and memoize the generated symbol manifest for a Font Awesome style.
+ * Build the path to a generated static symbol document.
  */
-export async function getIconStyleManifest(style: string): Promise<StyleIconSymbolManifest | null> {
-    const load = loaders[style as SupportedSymbolStyle];
-    if (!load) {
+function getStaticSymbolPath(style: string, icon: string): string {
+    return joinPath('icon-symbols', style, `${icon}.svg`);
+}
+
+function buildSymbolMarkup(symbolId: string, viewBox: string, markup: string) {
+    return `<symbol id="${escapeAttribute(symbolId)}" viewBox="${escapeAttribute(viewBox)}" overflow="visible">${markup}</symbol>`;
+}
+
+function buildSymbolDocument(symbolId: string, symbol: string) {
+    return `<svg xmlns="http://www.w3.org/2000/svg"><defs>${symbol}</defs><use href="#${escapeAttribute(symbolId)}"/></svg>`;
+}
+
+function parseSymbolDocument(document: string): IconSymbolSource | null {
+    const symbolMatch = document.match(symbolPattern);
+    if (!symbolMatch) {
+        return null;
+    }
+
+    const symbolAttributes = symbolMatch[1];
+    const rawMarkup = symbolMatch[2];
+    if (!symbolAttributes || rawMarkup === undefined) {
+        return null;
+    }
+
+    const viewBoxMatch = symbolAttributes.match(viewBoxPattern);
+    if (!viewBoxMatch) {
+        return null;
+    }
+    const viewBox = viewBoxMatch[1];
+    if (!viewBox) {
         return null;
     }
 
-    const existing = manifestPromises.get(style);
+    return {
+        viewBox,
+        markup: rawMarkup.trim(),
+    };
+}
+
+async function readLocalSymbolDocument(style: string, icon: string): Promise<string | null> {
+    const [{ readFile }, path] = await Promise.all([
+        import('node:fs/promises'),
+        import('node:path'),
+    ]);
+
+    try {
+        return await readFile(
+            path.resolve(
+                process.cwd(),
+                'public',
+                '~gitbook',
+                'static',
+                'icon-symbols',
+                style,
+                `${icon}.svg`
+            ),
+            'utf8'
+        );
+    } catch {
+        return null;
+    }
+}
+
+async function fetchSymbolDocument(style: string, icon: string): Promise<string | null> {
+    try {
+        const response = await fetch(getAssetURL(getStaticSymbolPath(style, icon)));
+        if (!response.ok) {
+            return null;
+        }
+
+        return response.text();
+    } catch {
+        return null;
+    }
+}
+
+async function loadSymbolSource(style: string, icon: string): Promise<IconSymbolSource | null> {
+    const cacheKey = `${style}/${icon}`;
+    const existing = symbolSources.get(cacheKey);
     if (existing) {
         return existing;
     }
 
-    const manifestPromise: Promise<StyleIconSymbolManifest> = load().then(
-        (module) => module.default as StyleIconSymbolManifest
-    );
-    manifestPromises.set(style, manifestPromise);
+    const sourcePromise = (async () => {
+        const document =
+            (GITBOOK_RUNTIME === 'cloudflare'
+                ? null
+                : await readLocalSymbolDocument(style, icon)) ??
+            (await fetchSymbolDocument(style, icon));
+        if (!document) {
+            return null;
+        }
+
+        return parseSymbolDocument(document);
+    })();
+    symbolSources.set(cacheKey, sourcePromise);
 
-    return manifestPromise;
+    return sourcePromise;
 }
 
 /**
- * Resolve one icon entry from the generated manifest and serialize it for sprite injection or
- * lazy-loading through the symbol route.
+ * Resolve one icon entry from the generated static symbol assets and serialize it for sprite
+ * injection or lazy-loading.
  */
 export async function getIconSymbol(style: string, icon: string, symbolId: string) {
-    const manifest = await getIconStyleManifest(style);
-    const entry = manifest?.[icon];
-    if (!entry) {
+    const source = await loadSymbolSource(style, icon);
+    if (!source) {
         return null;
     }
 
-    const symbol = `<symbol id="${escapeAttribute(symbolId)}" viewBox="${escapeAttribute(entry.viewBox)}" overflow="visible">${entry.markup}</symbol>`;
+    const symbol = buildSymbolMarkup(symbolId, source.viewBox, source.markup);
 
     return {
         style,
         icon,
         symbolId,
-        viewBox: entry.viewBox,
-        markup: entry.markup,
+        viewBox: source.viewBox,
+        markup: source.markup,
         symbol,
-        document: `<svg xmlns="http://www.w3.org/2000/svg"><defs>${symbol}</defs><use href="#${escapeAttribute(symbolId)}"/></svg>`,
+        document: buildSymbolDocument(symbolId, symbol),
     };
 }
diff --git a/packages/gitbook/src/lib/icons/types.ts b/packages/gitbook/src/lib/icons/types.ts
deleted file mode 100644
index de220e0a15..0000000000
--- a/packages/gitbook/src/lib/icons/types.ts
+++ /dev/null
@@ -1,6 +0,0 @@
-export interface StyleIconSymbolManifestEntry {
-    viewBox: string;
-    markup: string;
-}
-
-export type StyleIconSymbolManifest = Record<string, StyleIconSymbolManifestEntry>;
diff --git a/packages/icons/src/Icon.test.tsx b/packages/icons/src/Icon.test.tsx
index a91acb2887..5bff7da8dc 100644
--- a/packages/icons/src/Icon.test.tsx
+++ b/packages/icons/src/Icon.test.tsx
@@ -40,7 +40,7 @@ describe('Icon', () => {
                 assetsURL="https://icons.example.test"
                 iconStyle={IconStyle.Regular}
                 renderMode="symbol"
-                symbolLoaderURL="/~gitbook/icons/symbol"
+                symbolLoaderURL="/~gitbook/static/icon-symbols"
             >
                 <>
                     <Icon icon="github" />
diff --git a/packages/icons/src/IconSymbolLoader.tsx b/packages/icons/src/IconSymbolLoader.tsx
index c1c8720c3e..1fe139c27e 100644
--- a/packages/icons/src/IconSymbolLoader.tsx
+++ b/packages/icons/src/IconSymbolLoader.tsx
@@ -6,8 +6,8 @@ const SVG_NAMESPACE = 'http://www.w3.org/2000/svg';
 const pendingSymbolLoads = new Map<string, Promise<boolean>>();
 
 /**
- * Ensure a symbol referenced by an inline `<use>` exists after hydration, fetching it from the
- * internal symbol route only when the SSR sprite did not already include it.
+ * Ensure a symbol referenced by an inline `<use>` exists after hydration, fetching a static
+ * symbol document only when the SSR sprite did not already include it.
  */
 export function IconSymbolLoader(props: {
     instanceId: string;
@@ -78,7 +78,7 @@ function hasSymbol(symbolId: string): boolean {
 function buildSymbolURL(loaderURL: string, style: string, icon: string): string {
     const normalizedLoaderURL = loaderURL.endsWith('/') ? loaderURL.slice(0, -1) : loaderURL;
 
-    return `${normalizedLoaderURL}/${encodeURIComponent(style)}/${encodeURIComponent(icon)}`;
+    return `${normalizedLoaderURL}/${encodeURIComponent(style)}/${encodeURIComponent(icon)}.svg`;
 }
 
 function appendSymbolsFromDocument(markup: string): boolean {
diff --git a/packages/icons/src/IconsProvider.tsx b/packages/icons/src/IconsProvider.tsx
index 69cc1c8cc8..b25081b796 100644
--- a/packages/icons/src/IconsProvider.tsx
+++ b/packages/icons/src/IconsProvider.tsx
@@ -20,7 +20,7 @@ export type IconsContextType = Partial<IconsAssetsLocation> & {
     iconStyle: IconStyle;
     /** Rendering strategy for icons */
     renderMode: IconRenderMode;
-    /** Internal route used to lazily load symbols introduced after hydration */
+    /** Base URL used to lazily load prebuilt symbol documents introduced after hydration */
     symbolLoaderURL?: string;
 };
 

From e7f9bc2565a8898cff3d185bc7c3294223643e55 Mon Sep 17 00:00:00 2001
From: Brett Jephson <brett@gitbook.io>
Date: Thu, 30 Apr 2026 14:57:34 +0100
Subject: [PATCH 09/16] use route to transform svg to local symbol

---
 packages/gitbook/package.json                 |   1 -
 .../gitbook/scripts/generate-icon-symbols.js  | 134 -----------------
 packages/gitbook/scripts/generate.sh          |   1 -
 .../icons/symbol/[style]/[icon]/route.ts      |  28 ++++
 .../RootLayout/CustomizationRootLayout.tsx    |   2 +-
 .../src/lib/icons/supported-styles.json       |  14 --
 packages/gitbook/src/lib/icons/symbols.ts     | 142 ++++++++----------
 packages/icons/src/Icon.test.tsx              |   2 +-
 packages/icons/src/IconSymbolLoader.tsx       |   6 +-
 9 files changed, 94 insertions(+), 236 deletions(-)
 delete mode 100644 packages/gitbook/scripts/generate-icon-symbols.js
 create mode 100644 packages/gitbook/src/app/~gitbook/icons/symbol/[style]/[icon]/route.ts
 delete mode 100644 packages/gitbook/src/lib/icons/supported-styles.json

diff --git a/packages/gitbook/package.json b/packages/gitbook/package.json
index 56840a2cb4..b1d1f5fb84 100644
--- a/packages/gitbook/package.json
+++ b/packages/gitbook/package.json
@@ -118,7 +118,6 @@
         "rss-parser": "^3.13.0"
     },
     "scripts": {
-        "generate:icon-symbols": "node ./scripts/generate-icon-symbols.js",
         "generate": "./scripts/generate.sh",
         "clean": "rm -rf ./.next && rm -rf ./public/~gitbook/static/icon-symbols && rm -rf ./public/~gitbook/static/icons && rm -rf ./public/~gitbook/static/math",
         "dev": "env-cmd --silent -f ../../.env.local next --webpack",
diff --git a/packages/gitbook/scripts/generate-icon-symbols.js b/packages/gitbook/scripts/generate-icon-symbols.js
deleted file mode 100644
index 41073cf94f..0000000000
--- a/packages/gitbook/scripts/generate-icon-symbols.js
+++ /dev/null
@@ -1,134 +0,0 @@
-#!/usr/bin/env node
-const { existsSync } = require('node:fs');
-const fs = require('node:fs/promises');
-const path = require('node:path');
-
-const packageJSONPath = require.resolve('@gitbook/fontawesome-pro/package.json');
-const packageRoot = path.dirname(packageJSONPath);
-const supportedStyles = require('../src/lib/icons/supported-styles.json');
-const outputDirectory = path.resolve(__dirname, '../public/~gitbook/static/icon-symbols');
-const metadataPath = path.join(packageRoot, 'icons', 'metadata', 'icons.json');
-
-const svgPattern = /<svg\b([^>]*)>([\s\S]*?)<\/svg>\s*$/i;
-const symbolPattern = /<symbol id="([^"]+)" viewBox="([^"]+)">([\s\S]*?)<\/symbol>/g;
-const viewBoxPattern = /\bviewBox="([^"]+)"/i;
-const commentPattern = /<!--[\s\S]*?-->/g;
-
-function sanitizeSymbolFragment(fragment) {
-    return fragment.replace(/[^a-zA-Z0-9_-]/g, '-');
-}
-
-function getSymbolId(style, icon) {
-    return `gb-icon-${sanitizeSymbolFragment(style)}-${sanitizeSymbolFragment(icon)}`;
-}
-
-function buildSymbolDocumentFromSource(style, icon, source) {
-    const symbolId = getSymbolId(style, icon);
-
-    return `<svg xmlns="http://www.w3.org/2000/svg"><defs><symbol id="${symbolId}" viewBox="${source.viewBox}" overflow="visible">${source.markup}</symbol></defs><use href="#${symbolId}"/></svg>`;
-}
-
-function getSymbolSourceFromSVG(svgMarkup, style, icon) {
-    const svgMatch = svgMarkup.match(svgPattern);
-    if (!svgMatch) {
-        throw new Error(`Invalid SVG source for "${style}/${icon}"`);
-    }
-
-    const [, svgAttributes, innerMarkup] = svgMatch;
-    const viewBoxMatch = svgAttributes.match(viewBoxPattern);
-    if (!viewBoxMatch) {
-        throw new Error(`Missing viewBox for "${style}/${icon}"`);
-    }
-
-    return {
-        viewBox: viewBoxMatch[1],
-        markup: innerMarkup.replace(commentPattern, '').trim(),
-    };
-}
-
-async function main() {
-    await fs.rm(outputDirectory, { recursive: true, force: true });
-    await fs.mkdir(outputDirectory, { recursive: true });
-    const iconMetadata = JSON.parse(await fs.readFile(metadataPath, 'utf8'));
-
-    await Promise.all(
-        supportedStyles.map(async (style) => {
-            const stylePath = path.join(packageRoot, 'icons', 'svgs', style);
-            const spritePath = path.join(packageRoot, 'icons', 'sprites', `${style}.svg`);
-            if (!existsSync(stylePath)) {
-                if (!existsSync(spritePath)) {
-                    throw new Error(
-                        `Missing SVG directory and sprite file for "${style}": ${stylePath}, ${spritePath}`
-                    );
-                }
-            }
-
-            const styleOutputDirectory = path.join(outputDirectory, style);
-            await fs.mkdir(styleOutputDirectory, { recursive: true });
-            const generatedIcons = new Map();
-
-            if (existsSync(stylePath)) {
-                const sourceFiles = await fs.readdir(stylePath, { withFileTypes: true });
-                await Promise.all(
-                    sourceFiles
-                        .filter((entry) => entry.isFile() && entry.name.endsWith('.svg'))
-                        .map(async (entry) => {
-                            const sourcePath = path.join(stylePath, entry.name);
-                            const icon = path.basename(entry.name, '.svg');
-                            const svgMarkup = await fs.readFile(sourcePath, 'utf8');
-                            const symbolSource = getSymbolSourceFromSVG(svgMarkup, style, icon);
-
-                            generatedIcons.set(icon, symbolSource);
-                            await fs.writeFile(
-                                path.join(styleOutputDirectory, entry.name),
-                                buildSymbolDocumentFromSource(style, icon, symbolSource),
-                                'utf8'
-                            );
-                        })
-                );
-            } else {
-                const sprite = await fs.readFile(spritePath, 'utf8');
-                await Promise.all(
-                    [...sprite.matchAll(symbolPattern)].map(async (match) => {
-                        const [, icon, viewBox, markup] = match;
-                        const symbolSource = {
-                            viewBox,
-                            markup: markup.replace(commentPattern, '').trim(),
-                        };
-
-                        generatedIcons.set(icon, symbolSource);
-                        await fs.writeFile(
-                            path.join(styleOutputDirectory, `${icon}.svg`),
-                            buildSymbolDocumentFromSource(style, icon, symbolSource),
-                            'utf8'
-                        );
-                    })
-                );
-            }
-
-            await Promise.all(
-                [...generatedIcons.entries()].flatMap(([icon, symbolSource]) => {
-                    const aliases = iconMetadata[icon]?.aliases?.names ?? [];
-                    return aliases
-                        .filter((alias) => !generatedIcons.has(alias))
-                        .map(async (alias) => {
-                            generatedIcons.set(alias, symbolSource);
-                            await fs.writeFile(
-                                path.join(styleOutputDirectory, `${alias}.svg`),
-                                buildSymbolDocumentFromSource(style, alias, symbolSource),
-                                'utf8'
-                            );
-                        });
-                })
-            );
-        })
-    );
-
-    // biome-ignore lint/suspicious/noConsole: CLI output is useful when regenerating assets.
-    console.log(`Generated symbol SVGs for ${supportedStyles.length} styles in ${outputDirectory}`);
-}
-
-main().catch((error) => {
-    console.error(`Error generating icon symbols: ${error}`);
-    process.exit(1);
-});
diff --git a/packages/gitbook/scripts/generate.sh b/packages/gitbook/scripts/generate.sh
index 28e9aaf830..a1cfab43bd 100755
--- a/packages/gitbook/scripts/generate.sh
+++ b/packages/gitbook/scripts/generate.sh
@@ -5,7 +5,6 @@ set -o pipefail
 
 # Copy the assets
 gitbook-icons ./public/~gitbook/static/icons custom-icons
-bun run generate:icon-symbols
 gitbook-math ./public/~gitbook/static/math
 cp -r ../embed/standalone/ ./public/~gitbook/static/embed
 
diff --git a/packages/gitbook/src/app/~gitbook/icons/symbol/[style]/[icon]/route.ts b/packages/gitbook/src/app/~gitbook/icons/symbol/[style]/[icon]/route.ts
new file mode 100644
index 0000000000..f008cc42a5
--- /dev/null
+++ b/packages/gitbook/src/app/~gitbook/icons/symbol/[style]/[icon]/route.ts
@@ -0,0 +1,28 @@
+import { type NextRequest, NextResponse } from 'next/server';
+
+import { getIconSymbol } from '@/lib/icons/symbols';
+import { getIconSymbolId } from '@gitbook/icons';
+
+export async function GET(
+    _request: NextRequest,
+    { params }: { params: Promise<{ style: string; icon: string }> }
+) {
+    const { style, icon } = await params;
+    const symbol = await getIconSymbol(style, icon, getIconSymbolId(style, icon));
+
+    if (!symbol) {
+        return NextResponse.json(
+            {
+                error: 'Symbol not found',
+            },
+            { status: 404 }
+        );
+    }
+
+    return new NextResponse(symbol.document, {
+        headers: {
+            'content-type': 'image/svg+xml; charset=utf-8',
+            'cache-control': 'public, max-age=31536000, immutable',
+        },
+    });
+}
diff --git a/packages/gitbook/src/components/RootLayout/CustomizationRootLayout.tsx b/packages/gitbook/src/components/RootLayout/CustomizationRootLayout.tsx
index ca2a96e807..22583c0675 100644
--- a/packages/gitbook/src/components/RootLayout/CustomizationRootLayout.tsx
+++ b/packages/gitbook/src/components/RootLayout/CustomizationRootLayout.tsx
@@ -199,7 +199,7 @@ export async function CustomizationRootLayout(props: {
                         },
                     }}
                     renderMode="symbol"
-                    symbolLoaderURL="/~gitbook/static/icon-symbols"
+                    symbolLoaderURL="/~gitbook/icons/symbol"
                     iconStyle={iconStyle}
                 >
                     <RootLayoutClientContexts language={language}>
diff --git a/packages/gitbook/src/lib/icons/supported-styles.json b/packages/gitbook/src/lib/icons/supported-styles.json
deleted file mode 100644
index 38879ea4fe..0000000000
--- a/packages/gitbook/src/lib/icons/supported-styles.json
+++ /dev/null
@@ -1,14 +0,0 @@
-[
-    "brands",
-    "custom-icons",
-    "duotone",
-    "light",
-    "regular",
-    "sharp-duotone-solid",
-    "sharp-light",
-    "sharp-regular",
-    "sharp-solid",
-    "sharp-thin",
-    "solid",
-    "thin"
-]
diff --git a/packages/gitbook/src/lib/icons/symbols.ts b/packages/gitbook/src/lib/icons/symbols.ts
index b2c9fe0e2b..07586b7be7 100644
--- a/packages/gitbook/src/lib/icons/symbols.ts
+++ b/packages/gitbook/src/lib/icons/symbols.ts
@@ -1,18 +1,20 @@
 import 'server-only';
 
 import { getAssetURL } from '@/lib/assets';
-import { GITBOOK_RUNTIME } from '@/lib/env';
-import { joinPath } from '@/lib/paths';
+import { GITBOOK_ICONS_TOKEN, GITBOOK_ICONS_URL } from '@/lib/env';
+import { joinPath, joinPathWithBaseURL } from '@/lib/paths';
+
+const ICON_ASSET_VERSION = '2';
+const rawSvgPromises = new Map<string, Promise<string | null>>();
+const svgPattern = /<svg\b([^>]*)>([\s\S]*?)<\/svg>\s*$/i;
+const viewBoxPattern = /\bviewBox="([^"]+)"/i;
+const commentPattern = /<!--[\s\S]*?-->/g;
 
 interface IconSymbolSource {
     viewBox: string;
     markup: string;
 }
 
-const symbolSources = new Map<string, Promise<IconSymbolSource | null>>();
-const symbolPattern = /<symbol\b([^>]*)>([\s\S]*?)<\/symbol>/i;
-const viewBoxPattern = /\bviewBox="([^"]+)"/i;
-
 function escapeAttribute(value: string): string {
     return value
         .replaceAll('&', '&amp;')
@@ -21,115 +23,93 @@ function escapeAttribute(value: string): string {
         .replaceAll('>', '&gt;');
 }
 
-/**
- * Build the path to a generated static symbol document.
- */
-function getStaticSymbolPath(style: string, icon: string): string {
-    return joinPath('icon-symbols', style, `${icon}.svg`);
-}
+function getIconAssetBaseURL(style: string): string {
+    if (style === 'custom-icons') {
+        return getAssetURL('icons');
+    }
 
-function buildSymbolMarkup(symbolId: string, viewBox: string, markup: string) {
-    return `<symbol id="${escapeAttribute(symbolId)}" viewBox="${escapeAttribute(viewBox)}" overflow="visible">${markup}</symbol>`;
+    return GITBOOK_ICONS_URL;
 }
 
-function buildSymbolDocument(symbolId: string, symbol: string) {
-    return `<svg xmlns="http://www.w3.org/2000/svg"><defs>${symbol}</defs><use href="#${escapeAttribute(symbolId)}"/></svg>`;
-}
+function getIconAssetURL(style: string, icon: string): string {
+    const url = new URL(
+        joinPathWithBaseURL(getIconAssetBaseURL(style), joinPath('svgs', style, `${icon}.svg`))
+    );
+    url.searchParams.set('v', ICON_ASSET_VERSION);
 
-function parseSymbolDocument(document: string): IconSymbolSource | null {
-    const symbolMatch = document.match(symbolPattern);
-    if (!symbolMatch) {
-        return null;
+    if (style !== 'custom-icons' && GITBOOK_ICONS_TOKEN) {
+        url.searchParams.set('token', GITBOOK_ICONS_TOKEN);
     }
 
-    const symbolAttributes = symbolMatch[1];
-    const rawMarkup = symbolMatch[2];
-    if (!symbolAttributes || rawMarkup === undefined) {
+    return url.toString();
+}
+
+function parseRawSVG(document: string): IconSymbolSource | null {
+    const svgMatch = document.match(svgPattern);
+    if (!svgMatch) {
         return null;
     }
 
-    const viewBoxMatch = symbolAttributes.match(viewBoxPattern);
-    if (!viewBoxMatch) {
+    const svgAttributes = svgMatch[1];
+    const rawMarkup = svgMatch[2];
+    if (!svgAttributes || rawMarkup === undefined) {
         return null;
     }
-    const viewBox = viewBoxMatch[1];
+
+    const viewBoxMatch = svgAttributes.match(viewBoxPattern);
+    const viewBox = viewBoxMatch?.[1];
     if (!viewBox) {
         return null;
     }
 
     return {
         viewBox,
-        markup: rawMarkup.trim(),
+        markup: rawMarkup.replace(commentPattern, '').trim(),
     };
 }
 
-async function readLocalSymbolDocument(style: string, icon: string): Promise<string | null> {
-    const [{ readFile }, path] = await Promise.all([
-        import('node:fs/promises'),
-        import('node:path'),
-    ]);
-
-    try {
-        return await readFile(
-            path.resolve(
-                process.cwd(),
-                'public',
-                '~gitbook',
-                'static',
-                'icon-symbols',
-                style,
-                `${icon}.svg`
-            ),
-            'utf8'
-        );
-    } catch {
-        return null;
-    }
+function buildSymbolMarkup(symbolId: string, viewBox: string, markup: string) {
+    return `<symbol id="${escapeAttribute(symbolId)}" viewBox="${escapeAttribute(viewBox)}" overflow="visible">${markup}</symbol>`;
 }
 
-async function fetchSymbolDocument(style: string, icon: string): Promise<string | null> {
-    try {
-        const response = await fetch(getAssetURL(getStaticSymbolPath(style, icon)));
-        if (!response.ok) {
-            return null;
-        }
-
-        return response.text();
-    } catch {
-        return null;
-    }
+function buildSymbolDocument(symbolId: string, symbol: string) {
+    return `<svg xmlns="http://www.w3.org/2000/svg"><defs>${symbol}</defs><use href="#${escapeAttribute(symbolId)}"/></svg>`;
 }
 
-async function loadSymbolSource(style: string, icon: string): Promise<IconSymbolSource | null> {
+async function fetchRawSVG(style: string, icon: string): Promise<string | null> {
     const cacheKey = `${style}/${icon}`;
-    const existing = symbolSources.get(cacheKey);
+    const existing = rawSvgPromises.get(cacheKey);
     if (existing) {
         return existing;
     }
 
-    const sourcePromise = (async () => {
-        const document =
-            (GITBOOK_RUNTIME === 'cloudflare'
-                ? null
-                : await readLocalSymbolDocument(style, icon)) ??
-            (await fetchSymbolDocument(style, icon));
-        if (!document) {
-            return null;
-        }
-
-        return parseSymbolDocument(document);
-    })();
-    symbolSources.set(cacheKey, sourcePromise);
-
-    return sourcePromise;
+    const request = fetch(getIconAssetURL(style, icon), {
+        cache: 'force-cache',
+    })
+        .then(async (response) => {
+            if (!response.ok) {
+                return null;
+            }
+
+            return response.text();
+        })
+        .catch(() => null);
+
+    rawSvgPromises.set(cacheKey, request);
+    return request;
 }
 
 /**
- * Resolve one icon entry from the generated static symbol assets and serialize it for sprite
- * injection or lazy-loading.
+ * Resolve one icon entry from the raw SVG source and serialize it for sprite injection or
+ * same-origin lazy loading.
  */
 export async function getIconSymbol(style: string, icon: string, symbolId: string) {
-    const source = await loadSymbolSource(style, icon);
+    const rawSVG = await fetchRawSVG(style, icon);
+    if (!rawSVG) {
+        return null;
+    }
+
+    const source = parseRawSVG(rawSVG);
     if (!source) {
         return null;
     }
diff --git a/packages/icons/src/Icon.test.tsx b/packages/icons/src/Icon.test.tsx
index 5bff7da8dc..a91acb2887 100644
--- a/packages/icons/src/Icon.test.tsx
+++ b/packages/icons/src/Icon.test.tsx
@@ -40,7 +40,7 @@ describe('Icon', () => {
                 assetsURL="https://icons.example.test"
                 iconStyle={IconStyle.Regular}
                 renderMode="symbol"
-                symbolLoaderURL="/~gitbook/static/icon-symbols"
+                symbolLoaderURL="/~gitbook/icons/symbol"
             >
                 <>
                     <Icon icon="github" />
diff --git a/packages/icons/src/IconSymbolLoader.tsx b/packages/icons/src/IconSymbolLoader.tsx
index 1fe139c27e..71993de114 100644
--- a/packages/icons/src/IconSymbolLoader.tsx
+++ b/packages/icons/src/IconSymbolLoader.tsx
@@ -6,8 +6,8 @@ const SVG_NAMESPACE = 'http://www.w3.org/2000/svg';
 const pendingSymbolLoads = new Map<string, Promise<boolean>>();
 
 /**
- * Ensure a symbol referenced by an inline `<use>` exists after hydration, fetching a static
- * symbol document only when the SSR sprite did not already include it.
+ * Ensure a symbol referenced by an inline `<use>` exists after hydration, fetching it from the
+ * same-origin symbol route only when the SSR sprite did not already include it.
  */
 export function IconSymbolLoader(props: {
     instanceId: string;
@@ -78,7 +78,7 @@ function hasSymbol(symbolId: string): boolean {
 function buildSymbolURL(loaderURL: string, style: string, icon: string): string {
     const normalizedLoaderURL = loaderURL.endsWith('/') ? loaderURL.slice(0, -1) : loaderURL;
 
-    return `${normalizedLoaderURL}/${encodeURIComponent(style)}/${encodeURIComponent(icon)}.svg`;
+    return `${normalizedLoaderURL}/${encodeURIComponent(style)}/${encodeURIComponent(icon)}`;
 }
 
 function appendSymbolsFromDocument(markup: string): boolean {

From f232b8fff5203511c6b8e60e62598391aa71a3ee Mon Sep 17 00:00:00 2001
From: Brett Jephson <brett@gitbook.io>
Date: Thu, 30 Apr 2026 15:01:32 +0100
Subject: [PATCH 10/16] e2e tests

---
 packages/gitbook/e2e/util.ts | 24 ++++++++++++++++++------
 1 file changed, 18 insertions(+), 6 deletions(-)

diff --git a/packages/gitbook/e2e/util.ts b/packages/gitbook/e2e/util.ts
index 15d8bb99a6..6a16a975b0 100644
--- a/packages/gitbook/e2e/util.ts
+++ b/packages/gitbook/e2e/util.ts
@@ -146,6 +146,11 @@ export const headerLinks: CustomizationHeaderItem[] = [
     },
 ];
 
+type IconURLState = { state: 'pending'; uri: null } | { state: 'loaded'; uri: string };
+type IconStateWindow = Window & {
+    __ICONS_STATES__?: Record<string, IconURLState>;
+};
+
 export async function waitForCookiesDialog(page: Page) {
     const dialog = page.getByTestId('cookies-dialog');
     await expect(dialog).toBeVisible({
@@ -396,11 +401,9 @@ export function getCustomizationURL(partial: DeepPartial<SiteCustomizationSettin
  */
 export async function waitForIcons(page: Page) {
     await page.waitForFunction(() => {
-        const urlStates: Record<
-            string,
-            { state: 'pending'; uri: null } | { state: 'loaded'; uri: string }
-        > = (window as any).__ICONS_STATES__ || {};
-        (window as any).__ICONS_STATES__ = urlStates;
+        const iconWindow = window as IconStateWindow;
+        const urlStates: Record<string, IconURLState> = iconWindow.__ICONS_STATES__ || {};
+        iconWindow.__ICONS_STATES__ = urlStates;
 
         const fetchSvgAsDataUri = async (url: string): Promise<string> => {
             const response = await fetch(url);
@@ -435,7 +438,16 @@ export async function waitForIcons(page: Page) {
 
             const svgSymbol = icon.querySelector('[data-testid="symbol-use"]');
             if (svgSymbol) {
-                return icon.dataset.gbIIconSymbolState === 'loaded';
+                if (icon.dataset.gbIconSymbolState === 'loaded') {
+                    return true;
+                }
+
+                const href = svgSymbol.getAttribute('href') ?? svgSymbol.getAttribute('xlink:href');
+                if (!href?.startsWith('#')) {
+                    return false;
+                }
+
+                return document.getElementById(href.slice(1)) instanceof SVGElement;
             }
 
             const state = icon.getAttribute('data-argos-state');

From 9ad85cb30c1d9f14a79ab3ab36919e7556bd6f8f Mon Sep 17 00:00:00 2001
From: Brett Jephson <brett@gitbook.io>
Date: Thu, 30 Apr 2026 15:05:58 +0100
Subject: [PATCH 11/16] tidy

---
 packages/gitbook/package.json | 4 ++--
 turbo.json                    | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/gitbook/package.json b/packages/gitbook/package.json
index b1d1f5fb84..e713aefdbe 100644
--- a/packages/gitbook/package.json
+++ b/packages/gitbook/package.json
@@ -119,7 +119,7 @@
     },
     "scripts": {
         "generate": "./scripts/generate.sh",
-        "clean": "rm -rf ./.next && rm -rf ./public/~gitbook/static/icon-symbols && rm -rf ./public/~gitbook/static/icons && rm -rf ./public/~gitbook/static/math",
+        "clean": "rm -rf ./.next && rm -rf ./public/~gitbook/static/icons && rm -rf ./public/~gitbook/static/math",
         "dev": "env-cmd --silent -f ../../.env.local next --webpack",
         "build": "next build --webpack",
         "build:local": "GITBOOK_URL=http://localhost:3000 next build --webpack",
@@ -145,4 +145,4 @@
         "@types/react": "19.2.14",
         "@types/react-dom": "19.2.3"
     }
-}
+}
\ No newline at end of file
diff --git a/turbo.json b/turbo.json
index f35d59d56c..d9031e75c3 100644
--- a/turbo.json
+++ b/turbo.json
@@ -13,7 +13,7 @@
         // Prepare the package for all other tasks
         "generate": {
             "dependsOn": ["^generate"],
-            "outputs": ["dist", ".generated/**"]
+            "outputs": ["dist"]
         },
         // Build the package for publishing
         "build": {

From 6246b106af047467b8e7cef214d52a3c5ac480f5 Mon Sep 17 00:00:00 2001
From: Brett Jephson <brett@gitbook.io>
Date: Thu, 30 Apr 2026 15:11:15 +0100
Subject: [PATCH 12/16] formatting

---
 packages/gitbook/package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/gitbook/package.json b/packages/gitbook/package.json
index e713aefdbe..f67cb7c6de 100644
--- a/packages/gitbook/package.json
+++ b/packages/gitbook/package.json
@@ -145,4 +145,4 @@
         "@types/react": "19.2.14",
         "@types/react-dom": "19.2.3"
     }
-}
\ No newline at end of file
+}

From 5663064b46d0d61d02c5483112e57177d7f15d02 Mon Sep 17 00:00:00 2001
From: Brett Jephson <brett@gitbook.io>
Date: Thu, 30 Apr 2026 17:30:38 +0100
Subject: [PATCH 13/16] Speed up icon rendering

---
 packages/icons/src/Icon.tsx   |  7 +++++--
 packages/icons/src/symbols.ts | 35 +++++++++++++++++++++++++++++++++++
 2 files changed, 40 insertions(+), 2 deletions(-)

diff --git a/packages/icons/src/Icon.tsx b/packages/icons/src/Icon.tsx
index 402c40401e..7db56110c2 100644
--- a/packages/icons/src/Icon.tsx
+++ b/packages/icons/src/Icon.tsx
@@ -5,7 +5,7 @@ import * as React from 'react';
 import { IconSymbolLoader } from './IconSymbolLoader';
 import { getIconAssetURL, useIcons } from './IconsProvider';
 import { getIconStyle } from './getIconStyle';
-import { getIconSymbolId, registerServerIconSymbol } from './symbols';
+import { getIconSymbolId, prefetchServerIconAsset, registerServerIconSymbol } from './symbols';
 import type { IconName, IconStyle } from './types';
 
 /**
@@ -55,12 +55,15 @@ export const Icon = React.forwardRef(function Icon(
     const maskId = React.useId();
     const iconInstanceId = React.useId();
     const symbolId = getIconSymbolId(iconStyle, icon);
+    const iconAssetURL = getIconAssetURL(context, iconStyle, icon);
 
     if (context.renderMode === 'symbol') {
+        prefetchServerIconAsset(iconAssetURL);
         registerServerIconSymbol({
             style: iconStyle,
             icon,
             symbolId,
+            assetURL: iconAssetURL,
         });
 
         return (
@@ -111,7 +114,7 @@ export const Icon = React.forwardRef(function Icon(
                 >
                     <image
                         data-testid="mask-image"
-                        href={getIconAssetURL(context, iconStyle, icon)}
+                        href={iconAssetURL}
                         width="100%"
                         height="100%"
                         preserveAspectRatio="xMidYMid meet"
diff --git a/packages/icons/src/symbols.ts b/packages/icons/src/symbols.ts
index 4823e85ef8..f6e9c20ba6 100644
--- a/packages/icons/src/symbols.ts
+++ b/packages/icons/src/symbols.ts
@@ -4,9 +4,11 @@ export interface RegisteredIconSymbol {
     style: string;
     icon: string;
     symbolId: string;
+    assetURL?: string;
 }
 
 const REGISTERED_SYMBOLS_KEY = Symbol.for('gitbook.icons.registeredSymbols');
+const PREFETCHED_ICON_ASSETS_KEY = Symbol.for('gitbook.icons.prefetchedAssets');
 
 function sanitizeSymbolFragment(fragment: string): string {
     return fragment.replace(/[^a-zA-Z0-9_-]/g, '-');
@@ -31,6 +33,18 @@ function getRegisteredSymbolsStore(): Map<string, RegisteredIconSymbol> {
     return store[REGISTERED_SYMBOLS_KEY];
 }
 
+function getPrefetchedAssetsStore(): Map<string, Promise<void>> {
+    const store = globalThis as typeof globalThis & {
+        [PREFETCHED_ICON_ASSETS_KEY]?: Map<string, Promise<void>>;
+    };
+
+    if (!store[PREFETCHED_ICON_ASSETS_KEY]) {
+        store[PREFETCHED_ICON_ASSETS_KEY] = new Map<string, Promise<void>>();
+    }
+
+    return store[PREFETCHED_ICON_ASSETS_KEY];
+}
+
 function shouldTrackSymbolRegistrations() {
     const runtime = globalThis as typeof globalThis & { Bun?: unknown };
 
@@ -48,6 +62,27 @@ export function registerServerIconSymbol(symbol: RegisteredIconSymbol): void {
     getRegisteredSymbolsStore().set(`${symbol.style}/${symbol.icon}`, symbol);
 }
 
+/**
+ * Start fetching a raw SVG asset during SSR so sprite generation can reuse the in-flight or warm
+ * request instead of waiting until the end of the render.
+ */
+export function prefetchServerIconAsset(assetURL: string): void {
+    if (typeof window !== 'undefined') {
+        return;
+    }
+
+    const prefetchedAssets = getPrefetchedAssetsStore();
+    if (prefetchedAssets.has(assetURL)) {
+        return;
+    }
+
+    const request = fetch(assetURL, { cache: 'force-cache' })
+        .then(() => undefined)
+        .catch(() => undefined);
+
+    prefetchedAssets.set(assetURL, request);
+}
+
 /**
  * Return the currently registered server-rendered symbols in insertion order.
  */

From 9ce2759e1b12f689e4b8d0988e3195a5da57dac5 Mon Sep 17 00:00:00 2001
From: Brett Jephson <brett@gitbook.io>
Date: Thu, 30 Apr 2026 18:05:38 +0100
Subject: [PATCH 14/16] move spritesheet up

---
 .../src/components/RootLayout/CustomizationRootLayout.tsx       | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/gitbook/src/components/RootLayout/CustomizationRootLayout.tsx b/packages/gitbook/src/components/RootLayout/CustomizationRootLayout.tsx
index 22583c0675..2aba41edfd 100644
--- a/packages/gitbook/src/components/RootLayout/CustomizationRootLayout.tsx
+++ b/packages/gitbook/src/components/RootLayout/CustomizationRootLayout.tsx
@@ -202,10 +202,10 @@ export async function CustomizationRootLayout(props: {
                     symbolLoaderURL="/~gitbook/icons/symbol"
                     iconStyle={iconStyle}
                 >
+                    <IconSpriteDefinitions />
                     <RootLayoutClientContexts language={language}>
                         {children}
                     </RootLayoutClientContexts>
-                    <IconSpriteDefinitions />
                 </IconsProvider>
             </body>
         </html>

From 6d4a1653a2e649015de5e49618706b2bde12a1de Mon Sep 17 00:00:00 2001
From: Brett Jephson <brett@gitbook.io>
Date: Thu, 30 Apr 2026 18:52:05 +0100
Subject: [PATCH 15/16] use sprites to parse symbols

---
 packages/gitbook/src/lib/icons/symbols.ts | 81 +++++++++++++++++++++--
 packages/icons/src/Icon.tsx               |  6 +-
 packages/icons/src/IconsProvider.tsx      |  8 +++
 packages/icons/src/symbols.ts             |  5 +-
 4 files changed, 90 insertions(+), 10 deletions(-)

diff --git a/packages/gitbook/src/lib/icons/symbols.ts b/packages/gitbook/src/lib/icons/symbols.ts
index 07586b7be7..4a6a1eb601 100644
--- a/packages/gitbook/src/lib/icons/symbols.ts
+++ b/packages/gitbook/src/lib/icons/symbols.ts
@@ -6,8 +6,11 @@ import { joinPath, joinPathWithBaseURL } from '@/lib/paths';
 
 const ICON_ASSET_VERSION = '2';
 const rawSvgPromises = new Map<string, Promise<string | null>>();
+const styleSpritePromises = new Map<string, Promise<Map<string, IconSymbolSource> | null>>();
 const svgPattern = /<svg\b([^>]*)>([\s\S]*?)<\/svg>\s*$/i;
+const symbolPattern = /<symbol\b([^>]*)>([\s\S]*?)<\/symbol>/gi;
 const viewBoxPattern = /\bviewBox="([^"]+)"/i;
+const idPattern = /\bid="([^"]+)"/i;
 const commentPattern = /<!--[\s\S]*?-->/g;
 
 interface IconSymbolSource {
@@ -44,6 +47,19 @@ function getIconAssetURL(style: string, icon: string): string {
     return url.toString();
 }
 
+function getStyleSpriteAssetURL(style: string): string {
+    const url = new URL(
+        joinPathWithBaseURL(getIconAssetBaseURL(style), joinPath('sprites', `${style}.svg`))
+    );
+    url.searchParams.set('v', ICON_ASSET_VERSION);
+
+    if (style !== 'custom-icons' && GITBOOK_ICONS_TOKEN) {
+        url.searchParams.set('token', GITBOOK_ICONS_TOKEN);
+    }
+
+    return url.toString();
+}
+
 function parseRawSVG(document: string): IconSymbolSource | null {
     const svgMatch = document.match(svgPattern);
     if (!svgMatch) {
@@ -68,6 +84,35 @@ function parseRawSVG(document: string): IconSymbolSource | null {
     };
 }
 
+function parseStyleSprite(document: string): Map<string, IconSymbolSource> | null {
+    const symbols = new Map<string, IconSymbolSource>();
+
+    for (const match of document.matchAll(symbolPattern)) {
+        const symbolAttributes = match[1];
+        const rawMarkup = match[2];
+
+        if (!symbolAttributes || rawMarkup === undefined) {
+            continue;
+        }
+
+        const idMatch = symbolAttributes.match(idPattern);
+        const viewBoxMatch = symbolAttributes.match(viewBoxPattern);
+        const icon = idMatch?.[1];
+        const viewBox = viewBoxMatch?.[1];
+
+        if (!icon || !viewBox) {
+            continue;
+        }
+
+        symbols.set(icon, {
+            viewBox,
+            markup: rawMarkup.replace(commentPattern, '').trim(),
+        });
+    }
+
+    return symbols.size > 0 ? symbols : null;
+}
+
 function buildSymbolMarkup(symbolId: string, viewBox: string, markup: string) {
     return `<symbol id="${escapeAttribute(symbolId)}" viewBox="${escapeAttribute(viewBox)}" overflow="visible">${markup}</symbol>`;
 }
@@ -99,17 +144,45 @@ async function fetchRawSVG(style: string, icon: string): Promise<string | null>
     return request;
 }
 
+async function fetchStyleSprite(style: string): Promise<Map<string, IconSymbolSource> | null> {
+    const existing = styleSpritePromises.get(style);
+    if (existing) {
+        return existing;
+    }
+
+    const request = fetch(getStyleSpriteAssetURL(style), {
+        cache: 'force-cache',
+    })
+        .then(async (response) => {
+            if (!response.ok) {
+                return null;
+            }
+
+            return parseStyleSprite(await response.text());
+        })
+        .catch(() => null);
+
+    styleSpritePromises.set(style, request);
+    return request;
+}
+
 /**
  * Resolve one icon entry from the raw SVG source and serialize it for sprite injection or
  * same-origin lazy loading.
  */
 export async function getIconSymbol(style: string, icon: string, symbolId: string) {
-    const rawSVG = await fetchRawSVG(style, icon);
-    if (!rawSVG) {
-        return null;
+    const spriteSymbols = await fetchStyleSprite(style);
+    let source = spriteSymbols?.get(icon) ?? null;
+
+    if (!source) {
+        const rawSVG = await fetchRawSVG(style, icon);
+        if (!rawSVG) {
+            return null;
+        }
+
+        source = parseRawSVG(rawSVG);
     }
 
-    const source = parseRawSVG(rawSVG);
     if (!source) {
         return null;
     }
diff --git a/packages/icons/src/Icon.tsx b/packages/icons/src/Icon.tsx
index 7db56110c2..c82a9ea1f9 100644
--- a/packages/icons/src/Icon.tsx
+++ b/packages/icons/src/Icon.tsx
@@ -3,7 +3,7 @@
 import * as React from 'react';
 
 import { IconSymbolLoader } from './IconSymbolLoader';
-import { getIconAssetURL, useIcons } from './IconsProvider';
+import { getIconAssetURL, getIconSpriteAssetURL, useIcons } from './IconsProvider';
 import { getIconStyle } from './getIconStyle';
 import { getIconSymbolId, prefetchServerIconAsset, registerServerIconSymbol } from './symbols';
 import type { IconName, IconStyle } from './types';
@@ -56,14 +56,14 @@ export const Icon = React.forwardRef(function Icon(
     const iconInstanceId = React.useId();
     const symbolId = getIconSymbolId(iconStyle, icon);
     const iconAssetURL = getIconAssetURL(context, iconStyle, icon);
+    const iconSpriteAssetURL = getIconSpriteAssetURL(context, iconStyle);
 
     if (context.renderMode === 'symbol') {
-        prefetchServerIconAsset(iconAssetURL);
+        prefetchServerIconAsset(iconSpriteAssetURL);
         registerServerIconSymbol({
             style: iconStyle,
             icon,
             symbolId,
-            assetURL: iconAssetURL,
         });
 
         return (
diff --git a/packages/icons/src/IconsProvider.tsx b/packages/icons/src/IconsProvider.tsx
index b25081b796..2be9c0a38e 100644
--- a/packages/icons/src/IconsProvider.tsx
+++ b/packages/icons/src/IconsProvider.tsx
@@ -88,3 +88,11 @@ export function getIconAssetURL(context: IconsContextType, style: string, icon:
     const iconName = typeof icon === 'string' ? icon : String(icon);
     return getAssetURL(location, `svgs/${style}/${iconName}.svg`);
 }
+
+/**
+ * Get the URL for the sprite document of an icon style.
+ */
+export function getIconSpriteAssetURL(context: IconsContextType, style: string): string {
+    const location = context.assetsByStyles?.[style] ?? context;
+    return getAssetURL(location, `sprites/${style}.svg`);
+}
diff --git a/packages/icons/src/symbols.ts b/packages/icons/src/symbols.ts
index f6e9c20ba6..1d0f5bed88 100644
--- a/packages/icons/src/symbols.ts
+++ b/packages/icons/src/symbols.ts
@@ -4,7 +4,6 @@ export interface RegisteredIconSymbol {
     style: string;
     icon: string;
     symbolId: string;
-    assetURL?: string;
 }
 
 const REGISTERED_SYMBOLS_KEY = Symbol.for('gitbook.icons.registeredSymbols');
@@ -63,8 +62,8 @@ export function registerServerIconSymbol(symbol: RegisteredIconSymbol): void {
 }
 
 /**
- * Start fetching a raw SVG asset during SSR so sprite generation can reuse the in-flight or warm
- * request instead of waiting until the end of the render.
+ * Start fetching a server-side icon asset during SSR so sprite generation can reuse the in-flight
+ * or warm request instead of waiting until the end of the render.
  */
 export function prefetchServerIconAsset(assetURL: string): void {
     if (typeof window !== 'undefined') {

From 6cd9f2aaaa62db5e00f28e41cd42793a72f97fe8 Mon Sep 17 00:00:00 2001
From: Brett Jephson <brett@gitbook.io>
Date: Thu, 30 Apr 2026 20:38:57 +0100
Subject: [PATCH 16/16] update

---
 .../src/components/RootLayout/CustomizationRootLayout.tsx       | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/gitbook/src/components/RootLayout/CustomizationRootLayout.tsx b/packages/gitbook/src/components/RootLayout/CustomizationRootLayout.tsx
index 2aba41edfd..22583c0675 100644
--- a/packages/gitbook/src/components/RootLayout/CustomizationRootLayout.tsx
+++ b/packages/gitbook/src/components/RootLayout/CustomizationRootLayout.tsx
@@ -202,10 +202,10 @@ export async function CustomizationRootLayout(props: {
                     symbolLoaderURL="/~gitbook/icons/symbol"
                     iconStyle={iconStyle}
                 >
-                    <IconSpriteDefinitions />
                     <RootLayoutClientContexts language={language}>
                         {children}
                     </RootLayoutClientContexts>
+                    <IconSpriteDefinitions />
                 </IconsProvider>
             </body>
         </html>