From a28a9978517ae19c08b8dd3b61c98af2f7791d24 Mon Sep 17 00:00:00 2001
From: Zeno Kapitein <zeno@gitbook.io>
Date: Fri, 13 Jun 2025 15:42:00 +0200
Subject: [PATCH 01/23] Add margin to adjacent buttons (#3316)

---
 .changeset/purple-cougars-breathe.md          |  5 ++++
 .../components/DocumentView/InlineButton.tsx  | 30 +++++++++++--------
 2 files changed, 22 insertions(+), 13 deletions(-)
 create mode 100644 .changeset/purple-cougars-breathe.md
diff --git a/.changeset/purple-cougars-breathe.md b/.changeset/purple-cougars-breathe.md
new file mode 100644
index 000000000..2c6d010d4
--- /dev/null
+++ b/.changeset/purple-cougars-breathe.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Add margin to adjacent buttons
diff --git a/packages/gitbook/src/components/DocumentView/InlineButton.tsx b/packages/gitbook/src/components/DocumentView/InlineButton.tsx
index 9841c0262..a36cd7452 100644
--- a/packages/gitbook/src/components/DocumentView/InlineButton.tsx
+++ b/packages/gitbook/src/components/DocumentView/InlineButton.tsx
@@ -17,18 +17,22 @@ export async function InlineButton(props: InlineProps<api.DocumentInlineButton>)
     }
 
     return (
-        <Button
-            href={resolved.href}
-            label={inline.data.label}
-            // TODO: use a variant specifically for user-defined buttons.
-            variant={inline.data.kind}
-            insights={{
-                type: 'link_click',
-                link: {
-                    target: inline.data.ref,
-                    position: api.SiteInsightsLinkPosition.Content,
-                },
-            }}
-        />
+        // Set the leading to have some vertical space between adjacent buttons
+        <span className="inline-button leading-[3rem] [&:has(+.inline-button)]:mr-2">
+            <Button
+                href={resolved.href}
+                label={inline.data.label}
+                // TODO: use a variant specifically for user-defined buttons.
+                variant={inline.data.kind}
+                className="leading-normal"
+                insights={{
+                    type: 'link_click',
+                    link: {
+                        target: inline.data.ref,
+                        position: api.SiteInsightsLinkPosition.Content,
+                    },
+                }}
+            />
+        </span>
     );
 }

From 6294bbb53cffc9f7eb7487bd1a375b3c57622b17 Mon Sep 17 00:00:00 2001
From: conico974 <nicodorseuil@yahoo.fr>
Date: Fri, 13 Jun 2025 15:46:37 +0200
Subject: [PATCH 02/23] Fix error propagating (#3317)

Co-authored-by: Nicolas Dorseuil <nicolas@gitbook.io>
---
 .changeset/rotten-donuts-bow.md              |  5 +++++
 packages/gitbook-v2/src/app/global-error.tsx | 18 ++++++++++++++++++
 2 files changed, 23 insertions(+)
 create mode 100644 .changeset/rotten-donuts-bow.md
 create mode 100644 packages/gitbook-v2/src/app/global-error.tsx

diff --git a/.changeset/rotten-donuts-bow.md b/.changeset/rotten-donuts-bow.md
new file mode 100644
index 000000000..d6ebe0650
--- /dev/null
+++ b/.changeset/rotten-donuts-bow.md
@@ -0,0 +1,5 @@
+---
+"gitbook-v2": patch
+---
+
+add a global error boundary
diff --git a/packages/gitbook-v2/src/app/global-error.tsx b/packages/gitbook-v2/src/app/global-error.tsx
new file mode 100644
index 000000000..abf0186a4
--- /dev/null
+++ b/packages/gitbook-v2/src/app/global-error.tsx
@@ -0,0 +1,18 @@
+'use client';
+
+import NextError from 'next/error';
+
+export default function GlobalError({
+    error,
+}: {
+    error: Error & { digest?: string };
+}) {
+    console.error('Global error:', error);
+    return (
+        <html lang="en">
+            <body>
+                <NextError statusCode={undefined as any} />
+            </body>
+        </html>
+    );
+}

From 8a3910e208d83a0048e61f06e09e26cac263aef3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Samy=20Pess=C3=A9?= <samypesse@gmail.com>
Date: Fri, 13 Jun 2025 15:55:04 +0200
Subject: [PATCH 03/23] Experiment with hiding sections without a matching site
 space (#3318)

---
 .../SiteSections/encodeClientSiteSections.ts  | 48 +++++++++++++++++--
 1 file changed, 43 insertions(+), 5 deletions(-)

diff --git a/packages/gitbook/src/components/SiteSections/encodeClientSiteSections.ts b/packages/gitbook/src/components/SiteSections/encodeClientSiteSections.ts
index 1c8cd0989..891936b6f 100644
--- a/packages/gitbook/src/components/SiteSections/encodeClientSiteSections.ts
+++ b/packages/gitbook/src/components/SiteSections/encodeClientSiteSections.ts
@@ -1,5 +1,5 @@
 import { getSectionURL, getSiteSpaceURL } from '@/lib/sites';
-import type { SiteSection, SiteSectionGroup } from '@gitbook/api';
+import type { SiteSection, SiteSectionGroup, SiteSpace } from '@gitbook/api';
 import type { GitBookSiteContext, SiteSections } from '@v2/lib/context';
 
 export type ClientSiteSections = {
@@ -33,10 +33,14 @@ export function encodeClientSiteSections(context: GitBookSiteContext, sections:
                 title: item.title,
                 icon: item.icon,
                 object: item.object,
-                sections: item.sections.map((section) => encodeSection(context, section)),
+                sections: item.sections
+                    .filter((section) => shouldIncludeSection(context, section))
+                    .map((section) => encodeSection(context, section)),
             });
         } else {
-            clientSections.push(encodeSection(context, item));
+            if (shouldIncludeSection(context, item)) {
+                clientSections.push(encodeSection(context, item));
+            }
         }
     }
 
@@ -57,6 +61,33 @@ function encodeSection(context: GitBookSiteContext, section: SiteSection) {
     };
 }
 
+/**
+ * Test if a section should be included in the list of sections.
+ */
+function shouldIncludeSection(context: GitBookSiteContext, section: SiteSection) {
+    if (context.site.id !== 'site_JOVzv') {
+        return true;
+    }
+
+    // Testing for a new mode of navigation where the multi-variants section are hidden
+    // if they do not include an equivalent of the current site space.
+
+    // TODO: replace with a proper flag on the section
+    const withNavigateOnlyIfEquivalent = section.id === 'sitesc_4jvEm';
+
+    if (!withNavigateOnlyIfEquivalent) {
+        return true;
+    }
+
+    const { siteSpace: currentSiteSpace } = context;
+    if (section.siteSpaces.length === 1) {
+        return true;
+    }
+    return section.siteSpaces.some((siteSpace) =>
+        areSiteSpacesEquivalent(siteSpace, currentSiteSpace)
+    );
+}
+
 /**
  * Find the best default site space to navigate to for a givent section:
  * 1. If we are on the default, continue on the default.
@@ -70,8 +101,8 @@ function findBestTargetURL(context: GitBookSiteContext, section: SiteSection) {
         return getSectionURL(context, section);
     }
 
-    const bestMatch = section.siteSpaces.find(
-        (siteSpace) => siteSpace.path === currentSiteSpace.path
+    const bestMatch = section.siteSpaces.find((siteSpace) =>
+        areSiteSpacesEquivalent(siteSpace, currentSiteSpace)
     );
     if (bestMatch) {
         return getSiteSpaceURL(context, bestMatch);
@@ -79,3 +110,10 @@ function findBestTargetURL(context: GitBookSiteContext, section: SiteSection) {
 
     return getSectionURL(context, section);
 }
+
+/**
+ * Test if 2 site spaces are equivalent.
+ */
+function areSiteSpacesEquivalent(siteSpace1: SiteSpace, siteSpace2: SiteSpace) {
+    return siteSpace1.path === siteSpace2.path;
+}

From 87218062becd2272d66c7c93f0237461c6479a2a Mon Sep 17 00:00:00 2001
From: conico974 <nicodorseuil@yahoo.fr>
Date: Sat, 14 Jun 2025 11:10:26 +0200
Subject: [PATCH 04/23] Use Promise.all whenever possible (#3319)

Co-authored-by: Nicolas Dorseuil <nicolas@gitbook.io>
---
 .../src/components/Ads/AdClassicRendering.tsx | 12 ++--
 .../gitbook/src/components/Ads/renderAd.tsx   |  6 +-
 .../DocumentView/Table/RecordCard.tsx         | 16 +++---
 .../src/components/PageBody/PageCover.tsx     |  6 +-
 .../src/components/SiteLayout/SiteLayout.tsx  | 55 +++++++++++--------
 packages/gitbook/src/routes/ogimage.tsx       | 10 ++--
 6 files changed, 59 insertions(+), 46 deletions(-)

diff --git a/packages/gitbook/src/components/Ads/AdClassicRendering.tsx b/packages/gitbook/src/components/Ads/AdClassicRendering.tsx
index e6d263bf6..82613af49 100644
--- a/packages/gitbook/src/components/Ads/AdClassicRendering.tsx
+++ b/packages/gitbook/src/components/Ads/AdClassicRendering.tsx
@@ -19,14 +19,14 @@ export async function AdClassicRendering({
     insightsAd: SiteInsightsAd | null;
     context: GitBookBaseContext;
 }) {
-    const smallImgSrc =
+    const [smallImgSrc, logoSrc] = await Promise.all([
         'smallImage' in ad
-            ? await getResizedImageURL(context.imageResizer, ad.smallImage, { width: 192, dpr: 2 })
-            : null;
-    const logoSrc =
+            ? getResizedImageURL(context.imageResizer, ad.smallImage, { width: 192, dpr: 2 })
+            : null,
         'logo' in ad
-            ? await getResizedImageURL(context.imageResizer, ad.logo, { width: 192 - 48, dpr: 2 })
-            : null;
+            ? getResizedImageURL(context.imageResizer, ad.logo, { width: 192 - 48, dpr: 2 })
+            : null,
+    ]);
     return (
         <Link
             rel="sponsored noopener"
diff --git a/packages/gitbook/src/components/Ads/renderAd.tsx b/packages/gitbook/src/components/Ads/renderAd.tsx
index 146f0d253..96ff7bd3b 100644
--- a/packages/gitbook/src/components/Ads/renderAd.tsx
+++ b/packages/gitbook/src/components/Ads/renderAd.tsx
@@ -43,10 +43,12 @@ interface FetchPlaceholderAdOptions {
  * and properly access user-agent and IP.
  */
 export async function renderAd(options: FetchAdOptions) {
-    const context = isV2() ? await getServerActionBaseContext() : await getV1BaseContext();
+    const [context, result] = await Promise.all([
+        isV2() ? getServerActionBaseContext() : getV1BaseContext(),
+        options.source === 'live' ? fetchAd(options) : getPlaceholderAd(),
+    ]);
 
     const mode = options.source === 'live' ? options.mode : 'classic';
-    const result = options.source === 'live' ? await fetchAd(options) : await getPlaceholderAd();
     if (!result || !result.ad.description || !result.ad.statlink) {
         return null;
     }
diff --git a/packages/gitbook/src/components/DocumentView/Table/RecordCard.tsx b/packages/gitbook/src/components/DocumentView/Table/RecordCard.tsx
index 4bc1e0ce8..c32fb01e9 100644
--- a/packages/gitbook/src/components/DocumentView/Table/RecordCard.tsx
+++ b/packages/gitbook/src/components/DocumentView/Table/RecordCard.tsx
@@ -23,18 +23,18 @@ export async function RecordCard(
     const coverFile = view.coverDefinition
         ? getRecordValue<string[]>(record[1], view.coverDefinition)?.[0]
         : null;
-    const cover =
-        coverFile && context.contentContext
-            ? await resolveContentRef({ kind: 'file', file: coverFile }, context.contentContext)
-            : null;
-
     const targetRef = view.targetDefinition
         ? (record[1].values[view.targetDefinition] as ContentRef)
         : null;
-    const target =
+
+    const [cover, target] = await Promise.all([
+        coverFile && context.contentContext
+            ? resolveContentRef({ kind: 'file', file: coverFile }, context.contentContext)
+            : null,
         targetRef && context.contentContext
-            ? await resolveContentRef(targetRef, context.contentContext)
-            : null;
+            ? resolveContentRef(targetRef, context.contentContext)
+            : null,
+    ]);
 
     const coverIsSquareOrPortrait =
         cover?.file?.dimensions &&
diff --git a/packages/gitbook/src/components/PageBody/PageCover.tsx b/packages/gitbook/src/components/PageBody/PageCover.tsx
index a4bb71261..3b37dfd38 100644
--- a/packages/gitbook/src/components/PageBody/PageCover.tsx
+++ b/packages/gitbook/src/components/PageBody/PageCover.tsx
@@ -21,8 +21,10 @@ export async function PageCover(props: {
     context: GitBookSiteContext;
 }) {
     const { as, page, cover, context } = props;
-    const resolved = cover.ref ? await resolveContentRef(cover.ref, context) : null;
-    const resolvedDark = cover.refDark ? await resolveContentRef(cover.refDark, context) : null;
+    const [resolved, resolvedDark] = await Promise.all([
+        cover.ref ? resolveContentRef(cover.ref, context) : null,
+        cover.refDark ? resolveContentRef(cover.refDark, context) : null,
+    ]);
 
     return (
         <div
diff --git a/packages/gitbook/src/components/SiteLayout/SiteLayout.tsx b/packages/gitbook/src/components/SiteLayout/SiteLayout.tsx
index dda709526..83211354f 100644
--- a/packages/gitbook/src/components/SiteLayout/SiteLayout.tsx
+++ b/packages/gitbook/src/components/SiteLayout/SiteLayout.tsx
@@ -102,30 +102,37 @@ export async function generateSiteLayoutMetadata(context: GitBookSiteContext): P
     const customIcon = 'icon' in customization.favicon ? customization.favicon.icon : null;
 
     const faviconSize = 48;
-    const icons = [
-        {
-            url: customIcon?.light
-                ? await getResizedImageURL(imageResizer, customIcon.light, {
-                      width: faviconSize,
-                      height: faviconSize,
-                  })
-                : linker.toAbsoluteURL(
-                      linker.toPathInSpace('~gitbook/icon?size=small&theme=light')
-                  ),
-            type: 'image/png',
-            media: '(prefers-color-scheme: light)',
-        },
-        {
-            url: customIcon?.dark
-                ? await getResizedImageURL(imageResizer, customIcon.dark, {
-                      width: faviconSize,
-                      height: faviconSize,
-                  })
-                : linker.toAbsoluteURL(linker.toPathInSpace('~gitbook/icon?size=small&theme=dark')),
-            type: 'image/png',
-            media: '(prefers-color-scheme: dark)',
-        },
-    ];
+    const icons = await Promise.all(
+        [
+            {
+                url: customIcon?.light
+                    ? getResizedImageURL(imageResizer, customIcon.light, {
+                          width: faviconSize,
+                          height: faviconSize,
+                      })
+                    : linker.toAbsoluteURL(
+                          linker.toPathInSpace('~gitbook/icon?size=small&theme=light')
+                      ),
+                type: 'image/png',
+                media: '(prefers-color-scheme: light)',
+            },
+            {
+                url: customIcon?.dark
+                    ? getResizedImageURL(imageResizer, customIcon.dark, {
+                          width: faviconSize,
+                          height: faviconSize,
+                      })
+                    : linker.toAbsoluteURL(
+                          linker.toPathInSpace('~gitbook/icon?size=small&theme=dark')
+                      ),
+                type: 'image/png',
+                media: '(prefers-color-scheme: dark)',
+            },
+        ].map(async (icon) => ({
+            ...icon,
+            url: await icon.url,
+        }))
+    );
 
     return {
         title: site.title,
diff --git a/packages/gitbook/src/routes/ogimage.tsx b/packages/gitbook/src/routes/ogimage.tsx
index e55dcfc2d..e213ee223 100644
--- a/packages/gitbook/src/routes/ogimage.tsx
+++ b/packages/gitbook/src/routes/ogimage.tsx
@@ -45,7 +45,7 @@ export async function serveOGImage(baseContext: GitBookSiteContext, params: Page
             : '';
 
     // Load the fonts
-    const { fontFamily, fonts } = await (async () => {
+    const fontLoader = async () => {
         // google fonts
         if (typeof customization.styling.font === 'string') {
             const fontFamily = customization.styling.font ?? CustomizationDefaultFont.Inter;
@@ -85,7 +85,7 @@ export async function serveOGImage(baseContext: GitBookSiteContext, params: Page
         ).filter(filterOutNullable);
 
         return { fontFamily: 'CustomFont', fonts };
-    })();
+    };
 
     const theme = customization.themes.default;
     const useLightTheme = theme === 'light';
@@ -139,7 +139,7 @@ export async function serveOGImage(baseContext: GitBookSiteContext, params: Page
             break;
     }
 
-    const favicon = await (async () => {
+    const faviconLoader = async () => {
         if ('icon' in customization.favicon)
             return (
                 <img
@@ -164,7 +164,9 @@ export async function serveOGImage(baseContext: GitBookSiteContext, params: Page
             )
         );
         return <img src={src} alt="Icon" width={40} height={40} tw="mr-4" />;
-    })();
+    };
+
+    const [favicon, { fontFamily, fonts }] = await Promise.all([faviconLoader(), fontLoader()]);
 
     return new ImageResponse(
         <div

From 2863fe0dc17e2bf20dc8cb4137f72480024cc73a Mon Sep 17 00:00:00 2001
From: Taran Vohra <taranvohra@outlook.com>
Date: Mon, 16 Jun 2025 09:59:55 +0530
Subject: [PATCH 05/23] Use `resolvePublishedContentByUrl` instead of the
 deprecated resolution endpoint (#3310)

---
 packages/gitbook-v2/src/lib/data/lookup.ts | 97 +++++-----------------
 packages/gitbook-v2/src/middleware.ts      | 20 +----
 2 files changed, 24 insertions(+), 93 deletions(-)

diff --git a/packages/gitbook-v2/src/lib/data/lookup.ts b/packages/gitbook-v2/src/lib/data/lookup.ts
index 4c999bd7a..be8c21f1d 100644
--- a/packages/gitbook-v2/src/lib/data/lookup.ts
+++ b/packages/gitbook-v2/src/lib/data/lookup.ts
@@ -1,7 +1,7 @@
 import { race, tryCatch } from '@/lib/async';
 import { joinPath, joinPathWithBaseURL } from '@/lib/paths';
 import { trace } from '@/lib/tracing';
-import type { GitBookAPI, PublishedSiteContentLookup, SiteVisitorPayload } from '@gitbook/api';
+import type { PublishedSiteContentLookup, SiteVisitorPayload } from '@gitbook/api';
 import { apiClient } from './api';
 import { getExposableError } from './errors';
 import type { DataFetcherResponse } from './types';
@@ -18,85 +18,32 @@ interface LookupPublishedContentByUrlInput {
  * Lookup a content by its URL using the GitBook resolvePublishedContentByUrl API endpoint.
  * To optimize caching, we try multiple lookup alternatives and return the first one that matches.
  */
-export async function resolvePublishedContentByUrl(input: LookupPublishedContentByUrlInput) {
-    return lookupPublishedContentByUrl({
-        url: input.url,
-        fetchLookupAPIResult: ({ url, signal }) => {
-            const api = apiClient({ apiToken: input.apiToken });
-            return trace(
-                {
-                    operation: 'resolvePublishedContentByUrl',
-                    name: url,
-                },
-                () =>
-                    tryCatch(
-                        api.urls.resolvePublishedContentByUrl(
-                            {
-                                url,
-                                ...(input.visitorPayload ? { visitor: input.visitorPayload } : {}),
-                                redirectOnError: input.redirectOnError,
-                            },
-                            { signal }
-                        )
-                    )
-            );
-        },
-    });
-}
-
-/**
- * Lookup a content by its URL using the GitBook getPublishedContentByUrl API endpoint.
- * To optimize caching, we try multiple lookup alternatives and return the first one that matches.
- *
- * @deprecated use resolvePublishedContentByUrl.
- *
- */
-export async function getPublishedContentByURL(input: LookupPublishedContentByUrlInput) {
-    return lookupPublishedContentByUrl({
-        url: input.url,
-        fetchLookupAPIResult: ({ url, signal }) => {
-            const api = apiClient({ apiToken: input.apiToken });
-            return trace(
-                {
-                    operation: 'getPublishedContentByURL',
-                    name: url,
-                },
-                () =>
-                    tryCatch(
-                        api.urls.getPublishedContentByUrl(
-                            {
-                                url,
-                                visitorAuthToken: input.visitorPayload.jwtToken ?? undefined,
-                                redirectOnError: input.redirectOnError,
-                                // @ts-expect-error - cacheVersion is not a real query param
-                                cacheVersion: 'v2',
-                            },
-                            { signal }
-                        )
-                    )
-            );
-        },
-    });
-}
-
-type TryCatch<T> = ReturnType<typeof tryCatch<T>>;
-
-async function lookupPublishedContentByUrl(input: {
-    url: string;
-    fetchLookupAPIResult: (args: {
-        url: string;
-        signal: AbortSignal;
-    }) => TryCatch<Awaited<ReturnType<GitBookAPI['urls']['resolvePublishedContentByUrl']>>>;
-}): Promise<DataFetcherResponse<PublishedSiteContentLookup>> {
+export async function lookupPublishedContentByUrl(
+    input: LookupPublishedContentByUrlInput
+): Promise<DataFetcherResponse<PublishedSiteContentLookup>> {
     const lookupURL = new URL(input.url);
     const url = stripURLSearch(lookupURL);
     const lookup = getURLLookupAlternatives(url);
 
     const result = await race(lookup.urls, async (alternative, { signal }) => {
-        const callResult = await input.fetchLookupAPIResult({
-            url: alternative.url,
-            signal,
-        });
+        const api = apiClient({ apiToken: input.apiToken });
+        const callResult = await trace(
+            {
+                operation: 'resolvePublishedContentByUrl',
+                name: alternative.url,
+            },
+            () =>
+                tryCatch(
+                    api.urls.resolvePublishedContentByUrl(
+                        {
+                            url: alternative.url,
+                            ...(input.visitorPayload ? { visitor: input.visitorPayload } : {}),
+                            redirectOnError: input.redirectOnError,
+                        },
+                        { signal }
+                    )
+                )
+        );
 
         if (callResult.error) {
             if (alternative.primary) {
diff --git a/packages/gitbook-v2/src/middleware.ts b/packages/gitbook-v2/src/middleware.ts
index 0d57ce27e..d413d6a43 100644
--- a/packages/gitbook-v2/src/middleware.ts
+++ b/packages/gitbook-v2/src/middleware.ts
@@ -16,10 +16,9 @@ import {
 import { serveResizedImage } from '@/routes/image';
 import {
     DataFetcherError,
-    getPublishedContentByURL,
     getVisitorAuthBasePath,
+    lookupPublishedContentByUrl,
     normalizeURL,
-    resolvePublishedContentByUrl,
     throwIfDataError,
 } from '@v2/lib/data';
 import { isGitBookAssetsHostURL, isGitBookHostURL } from '@v2/lib/env';
@@ -34,18 +33,6 @@ export const config = {
 
 type URLWithMode = { url: URL; mode: 'url' | 'url-host' };
 
-/**
- * Temporary list of hosts to test adaptive content using the new resolution API.
- */
-const ADAPTIVE_CONTENT_HOSTS = [
-    'docs.gitbook.com',
-    'paypal.gitbook.com',
-    'adaptive-docs.gitbook-staging.com',
-    'enriched-content-playground.gitbook-staging.io',
-    'docs.testgitbook.com',
-    'launchdarkly-site.gitbook.education',
-];
-
 export async function middleware(request: NextRequest) {
     try {
         const requestURL = new URL(request.url);
@@ -104,11 +91,8 @@ async function serveSiteRoutes(requestURL: URL, request: NextRequest) {
     });
 
     const withAPIToken = async (apiToken: string | null) => {
-        const resolve = ADAPTIVE_CONTENT_HOSTS.includes(siteRequestURL.hostname)
-            ? resolvePublishedContentByUrl
-            : getPublishedContentByURL;
         const siteURLData = await throwIfDataError(
-            resolve({
+            lookupPublishedContentByUrl({
                 url: siteRequestURL.toString(),
                 visitorPayload: {
                     jwtToken: visitorToken?.token ?? undefined,

From 42d88da73ce7d0a71e20c60625571bc773443c56 Mon Sep 17 00:00:00 2001
From: Utku Ufuk <utkuufuk@gmail.com>
Date: Mon, 16 Jun 2025 12:31:15 +0200
Subject: [PATCH 06/23] Fix UX issue about highlighting the search term in
 search result sections (#3323)

---
 .changeset/afraid-gifts-sparkle.md              |  5 +++++
 README.md                                       | 10 ++++++++--
 .../Search/SearchSectionResultItem.tsx          | 17 ++++++++++++-----
 3 files changed, 25 insertions(+), 7 deletions(-)
 create mode 100644 .changeset/afraid-gifts-sparkle.md

diff --git a/.changeset/afraid-gifts-sparkle.md b/.changeset/afraid-gifts-sparkle.md
new file mode 100644
index 000000000..ec33c1efc
--- /dev/null
+++ b/.changeset/afraid-gifts-sparkle.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix UX issue about highlighting the search term in search result sections
diff --git a/README.md b/README.md
index 8a9f5c2fd..9b13767ff 100644
--- a/README.md
+++ b/README.md
@@ -56,13 +56,19 @@ git clone https://github.com/gitbookIO/gitbook.git
 bun install
 ```
 
-4. Start your local development server.
+4. Run build.
+
+```
+bun build:v2
+```
+
+5. Start your local development server.
 
 ```
 bun dev:v2
 ```
 
-5. Open a published GitBook space in your web browser, prefixing it with `http://localhost:3000/`.
+6. Open a published GitBook space in your web browser, prefixing it with `http://localhost:3000/`.
 
 examples:
 
diff --git a/packages/gitbook/src/components/Search/SearchSectionResultItem.tsx b/packages/gitbook/src/components/Search/SearchSectionResultItem.tsx
index 960b1eb38..a0f467f80 100644
--- a/packages/gitbook/src/components/Search/SearchSectionResultItem.tsx
+++ b/packages/gitbook/src/components/Search/SearchSectionResultItem.tsx
@@ -66,11 +66,7 @@ export const SearchSectionResultItem = React.forwardRef(function SearchSectionRe
                         <HighlightQuery query={query} text={item.title} />
                     </p>
                 ) : null}
-                {item.body ? (
-                    <p className={tcls('text-sm', 'line-clamp-3', 'relative')}>
-                        <HighlightQuery query={query} text={item.body} />
-                    </p>
-                ) : null}
+                {item.body ? highlightQueryInBody(item.body, query) : null}
             </div>
             <div
                 className={tcls(
@@ -90,3 +86,14 @@ export const SearchSectionResultItem = React.forwardRef(function SearchSectionRe
         </Link>
     );
 });
+
+function highlightQueryInBody(body: string, query: string) {
+    const idx = body.indexOf(query);
+
+    // Ensure the query to be highlighted is visible in the body.
+    return (
+        <p className={tcls('text-sm', 'line-clamp-3', 'relative')}>
+            <HighlightQuery query={query} text={idx < 20 ? body : `...${body.slice(idx - 15)}`} />
+        </p>
+    );
+}

From 72cd0e59e683ace3d269f0e59338b41c36b88651 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Samy=20Pess=C3=A9?= <samypesse@gmail.com>
Date: Mon, 16 Jun 2025 13:37:45 +0200
Subject: [PATCH 07/23] Replace withoutConcurrency by a smarter React.cache
 (#3325)

---
 .changeset/fuzzy-tables-jump.md             |    5 +
 bun.lock                                    |    3 +
 packages/gitbook-v2/package.json            |    3 +-
 packages/gitbook-v2/src/lib/cache.test.ts   |   80 ++
 packages/gitbook-v2/src/lib/cache.ts        |   59 +
 packages/gitbook-v2/src/lib/data/api.ts     | 1077 +++++++++----------
 packages/gitbook-v2/src/lib/data/memoize.ts |   92 --
 7 files changed, 658 insertions(+), 661 deletions(-)
 create mode 100644 .changeset/fuzzy-tables-jump.md
 create mode 100644 packages/gitbook-v2/src/lib/cache.test.ts
 create mode 100644 packages/gitbook-v2/src/lib/cache.ts
 delete mode 100644 packages/gitbook-v2/src/lib/data/memoize.ts

diff --git a/.changeset/fuzzy-tables-jump.md b/.changeset/fuzzy-tables-jump.md
new file mode 100644
index 000000000..ada33d1c5
--- /dev/null
+++ b/.changeset/fuzzy-tables-jump.md
@@ -0,0 +1,5 @@
+---
+"gitbook-v2": patch
+---
+
+Optimize performances by using a smarter per-request cache arround data cached functions
diff --git a/bun.lock b/bun.lock
index 3ff6d61c4..b4d2b49d1 100644
--- a/bun.lock
+++ b/bun.lock
@@ -169,6 +169,7 @@
         "assert-never": "^1.2.1",
         "jwt-decode": "^4.0.0",
         "next": "^15.3.2",
+        "object-identity": "^0.1.2",
         "react": "^19.0.0",
         "react-dom": "^19.0.0",
         "rison": "^0.1.1",
@@ -2438,6 +2439,8 @@
 
     "object-hash": ["object-hash@3.0.0", "", {}, "sha512-RSn9F68PjH9HqtltsSnqYC1XXoWe9Bju5+213R98cNGttag9q9yAOTzdbsqvIa7aNm5WffBZFpWYr2aWrklWAw=="],
 
+    "object-identity": ["object-identity@0.1.2", "", {}, "sha512-Px5puVllX5L2aBjbcfXpiG5xXeq6OE8RckryTeP2Zq+0PgYrCGJXmC6LblWgknKSJs11Je2W4U2NOWFj3t/QXQ=="],
+
     "object-inspect": ["object-inspect@1.13.2", "", {}, "sha512-IRZSRuzJiynemAXPYtPe5BoI/RESNYR7TYm50MC5Mqbd3Jmw5y790sErYw3V6SryFJD64b74qQQs9wn5Bg/k3g=="],
 
     "object-treeify": ["object-treeify@1.1.33", "", {}, "sha512-EFVjAYfzWqWsBMRHPMAXLCDIJnpMhdWAqR7xG6M6a2cs6PMFpl/+Z20w9zDW4vkxOFfddegBKq9Rehd0bxWE7A=="],
diff --git a/packages/gitbook-v2/package.json b/packages/gitbook-v2/package.json
index 5723cdbc7..cfa6e71b9 100644
--- a/packages/gitbook-v2/package.json
+++ b/packages/gitbook-v2/package.json
@@ -14,7 +14,8 @@
         "react-dom": "^19.0.0",
         "rison": "^0.1.1",
         "server-only": "^0.0.1",
-        "warn-once": "^0.1.1"
+        "warn-once": "^0.1.1",
+        "object-identity": "^0.1.2"
     },
     "devDependencies": {
         "gitbook": "*",
diff --git a/packages/gitbook-v2/src/lib/cache.test.ts b/packages/gitbook-v2/src/lib/cache.test.ts
new file mode 100644
index 000000000..735b1fb06
--- /dev/null
+++ b/packages/gitbook-v2/src/lib/cache.test.ts
@@ -0,0 +1,80 @@
+import { describe, expect, it } from 'bun:test';
+import { withStableRef } from './cache';
+
+describe('withStableRef', () => {
+    it('should return primitive values as is', () => {
+        const toStableRef = withStableRef();
+
+        expect(toStableRef(42)).toBe(42);
+        expect(toStableRef('hello')).toBe('hello');
+        expect(toStableRef(true)).toBe(true);
+        expect(toStableRef(null)).toBe(null);
+        expect(toStableRef(undefined)).toBe(undefined);
+    });
+
+    it('should return the same reference for identical objects', () => {
+        const toStableRef = withStableRef();
+
+        const obj1 = { a: 1, b: 2 };
+        const obj2 = { a: 1, b: 2 };
+
+        const ref1 = toStableRef(obj1);
+        const ref2 = toStableRef(obj2);
+
+        expect(ref1).toBe(ref2);
+        expect(ref1).toBe(obj1);
+        expect(ref1).not.toBe(obj2);
+    });
+
+    it('should return the same reference for identical arrays', () => {
+        const toStableRef = withStableRef();
+
+        const arr1 = [1, 2, 3];
+        const arr2 = [1, 2, 3];
+
+        const ref1 = toStableRef(arr1);
+        const ref2 = toStableRef(arr2);
+
+        expect(ref1).toBe(ref2);
+        expect(ref1).toBe(arr1);
+        expect(ref1).not.toBe(arr2);
+    });
+
+    it('should return the same reference for identical nested objects', () => {
+        const toStableRef = withStableRef();
+
+        const obj1 = { a: { b: 1 }, c: [2, 3] };
+        const obj2 = { a: { b: 1 }, c: [2, 3] };
+
+        const ref1 = toStableRef(obj1);
+        const ref2 = toStableRef(obj2);
+
+        expect(ref1).toBe(ref2);
+        expect(ref1).toBe(obj1);
+        expect(ref1).not.toBe(obj2);
+    });
+
+    it('should return different references for different objects', () => {
+        const toStableRef = withStableRef();
+
+        const obj1 = { a: 1 };
+        const obj2 = { a: 2 };
+
+        const ref1 = toStableRef(obj1);
+        const ref2 = toStableRef(obj2);
+
+        expect(ref1).not.toBe(ref2);
+    });
+
+    it('should maintain reference stability across multiple calls', () => {
+        const toStableRef = withStableRef();
+
+        const obj = { a: 1 };
+        const ref1 = toStableRef(obj);
+        const ref2 = toStableRef(obj);
+        const ref3 = toStableRef(obj);
+
+        expect(ref1).toBe(ref2);
+        expect(ref2).toBe(ref3);
+    });
+});
diff --git a/packages/gitbook-v2/src/lib/cache.ts b/packages/gitbook-v2/src/lib/cache.ts
new file mode 100644
index 000000000..e05753907
--- /dev/null
+++ b/packages/gitbook-v2/src/lib/cache.ts
@@ -0,0 +1,59 @@
+import { identify } from 'object-identity';
+import * as React from 'react';
+
+/**
+ * Equivalent to `React.cache` but with support for non-primitive arguments.
+ * As `React.cache` only uses `Object.is` to compare arguments, it will not work with non-primitive arguments.
+ */
+export function cache<Args extends any[], Return>(fn: (...args: Args) => Return) {
+    const cached = React.cache(fn);
+
+    return (...args: Args) => {
+        const toStableRef = getWithStableRef();
+        const stableArgs = args.map((value) => {
+            return toStableRef(value);
+        }) as Args;
+        return cached(...stableArgs);
+    };
+}
+
+/**
+ * To ensure memory is garbage collected between each request, we use a per-request cache to store the ref maps.
+ */
+const getWithStableRef = React.cache(withStableRef);
+
+/**
+ * Create a function that converts a value to a stable reference.
+ */
+export function withStableRef(): <T>(value: T) => T {
+    const reverseIndex = new WeakMap<object, string>();
+    const refIndex = new Map<string, object>();
+
+    return <T>(value: T) => {
+        if (isPrimitive(value)) {
+            return value;
+        }
+
+        const objectValue = value as object;
+        const index = reverseIndex.get(objectValue);
+        if (index !== undefined) {
+            return refIndex.get(index) as T;
+        }
+
+        const hash = identify(objectValue);
+        reverseIndex.set(objectValue, hash);
+
+        const existing = refIndex.get(hash);
+        if (existing !== undefined) {
+            return existing as T;
+        }
+
+        // first time we've seen this shape
+        refIndex.set(hash, objectValue);
+        return value;
+    };
+}
+
+function isPrimitive(value: any): boolean {
+    return value === null || typeof value !== 'object';
+}
diff --git a/packages/gitbook-v2/src/lib/data/api.ts b/packages/gitbook-v2/src/lib/data/api.ts
index 88c95c401..d36c2445f 100644
--- a/packages/gitbook-v2/src/lib/data/api.ts
+++ b/packages/gitbook-v2/src/lib/data/api.ts
@@ -8,8 +8,8 @@ import {
 import { getCacheTag, getComputedContentSourceCacheTags } from '@gitbook/cache-tags';
 import { GITBOOK_API_TOKEN, GITBOOK_API_URL, GITBOOK_USER_AGENT } from '@v2/lib/env';
 import { unstable_cacheLife as cacheLife, unstable_cacheTag as cacheTag } from 'next/cache';
+import { cache } from '../cache';
 import { DataFetcherError, wrapDataFetcherError } from './errors';
-import { withCacheKey, withoutConcurrentExecution } from './memoize';
 import type { GitBookDataFetcher } from './types';
 
 interface DataFetcherInput {
@@ -204,307 +204,149 @@ export function createDataFetcher(
     };
 }
 
-const getUserById = withCacheKey(
-    withoutConcurrentExecution(async (_, input: DataFetcherInput, params: { userId: string }) => {
+const getUserById = cache(async (input: DataFetcherInput, params: { userId: string }) => {
+    'use cache';
+    return trace(`getUserById(${params.userId})`, async () => {
+        return wrapDataFetcherError(async () => {
+            const api = apiClient(input);
+            const res = await api.users.getUserById(params.userId, {
+                ...noCacheFetchOptions,
+            });
+            cacheTag(...getCacheTagsFromResponse(res));
+            cacheLife('days');
+            return res.data;
+        });
+    });
+});
+
+const getSpace = cache(
+    async (input: DataFetcherInput, params: { spaceId: string; shareKey: string | undefined }) => {
         'use cache';
-        return trace(`getUserById(${params.userId})`, async () => {
+        cacheTag(
+            getCacheTag({
+                tag: 'space',
+                space: params.spaceId,
+            })
+        );
+
+        return trace(`getSpace(${params.spaceId}, ${params.shareKey})`, async () => {
             return wrapDataFetcherError(async () => {
                 const api = apiClient(input);
-                const res = await api.users.getUserById(params.userId, {
-                    ...noCacheFetchOptions,
-                });
+                const res = await api.spaces.getSpaceById(
+                    params.spaceId,
+                    {
+                        shareKey: params.shareKey,
+                    },
+                    {
+                        ...noCacheFetchOptions,
+                    }
+                );
                 cacheTag(...getCacheTagsFromResponse(res));
                 cacheLife('days');
                 return res.data;
             });
         });
-    })
+    }
 );
 
-const getSpace = withCacheKey(
-    withoutConcurrentExecution(
-        async (
-            _,
-            input: DataFetcherInput,
-            params: { spaceId: string; shareKey: string | undefined }
-        ) => {
-            'use cache';
-            cacheTag(
-                getCacheTag({
-                    tag: 'space',
-                    space: params.spaceId,
-                })
-            );
+const getChangeRequest = cache(
+    async (input: DataFetcherInput, params: { spaceId: string; changeRequestId: string }) => {
+        'use cache';
+        cacheTag(
+            getCacheTag({
+                tag: 'change-request',
+                space: params.spaceId,
+                changeRequest: params.changeRequestId,
+            })
+        );
 
-            return trace(`getSpace(${params.spaceId}, ${params.shareKey})`, async () => {
-                return wrapDataFetcherError(async () => {
-                    const api = apiClient(input);
-                    const res = await api.spaces.getSpaceById(
-                        params.spaceId,
-                        {
-                            shareKey: params.shareKey,
-                        },
-                        {
-                            ...noCacheFetchOptions,
-                        }
-                    );
-                    cacheTag(...getCacheTagsFromResponse(res));
-                    cacheLife('days');
-                    return res.data;
-                });
+        return trace(`getChangeRequest(${params.spaceId}, ${params.changeRequestId})`, async () => {
+            return wrapDataFetcherError(async () => {
+                const api = apiClient(input);
+                const res = await api.spaces.getChangeRequestById(
+                    params.spaceId,
+                    params.changeRequestId,
+                    {
+                        ...noCacheFetchOptions,
+                    }
+                );
+                cacheTag(...getCacheTagsFromResponse(res));
+                cacheLife('minutes');
+                return res.data;
             });
-        }
-    )
+        });
+    }
 );
 
-const getChangeRequest = withCacheKey(
-    withoutConcurrentExecution(
-        async (
-            _,
-            input: DataFetcherInput,
-            params: { spaceId: string; changeRequestId: string }
-        ) => {
-            'use cache';
-            cacheTag(
-                getCacheTag({
-                    tag: 'change-request',
-                    space: params.spaceId,
-                    changeRequest: params.changeRequestId,
-                })
-            );
-
-            return trace(
-                `getChangeRequest(${params.spaceId}, ${params.changeRequestId})`,
-                async () => {
-                    return wrapDataFetcherError(async () => {
-                        const api = apiClient(input);
-                        const res = await api.spaces.getChangeRequestById(
-                            params.spaceId,
-                            params.changeRequestId,
-                            {
-                                ...noCacheFetchOptions,
-                            }
-                        );
-                        cacheTag(...getCacheTagsFromResponse(res));
-                        cacheLife('minutes');
-                        return res.data;
-                    });
-                }
-            );
-        }
-    )
+const getRevision = cache(
+    async (
+        input: DataFetcherInput,
+        params: { spaceId: string; revisionId: string; metadata: boolean }
+    ) => {
+        'use cache';
+        return trace(`getRevision(${params.spaceId}, ${params.revisionId})`, async () => {
+            return wrapDataFetcherError(async () => {
+                const api = apiClient(input);
+                const res = await api.spaces.getRevisionById(
+                    params.spaceId,
+                    params.revisionId,
+                    {
+                        metadata: params.metadata,
+                    },
+                    {
+                        ...noCacheFetchOptions,
+                    }
+                );
+                cacheTag(...getCacheTagsFromResponse(res));
+                cacheLife('max');
+                return res.data;
+            });
+        });
+    }
 );
 
-const getRevision = withCacheKey(
-    withoutConcurrentExecution(
-        async (
-            _,
-            input: DataFetcherInput,
-            params: { spaceId: string; revisionId: string; metadata: boolean }
-        ) => {
-            'use cache';
-            return trace(`getRevision(${params.spaceId}, ${params.revisionId})`, async () => {
+const getRevisionPages = cache(
+    async (
+        input: DataFetcherInput,
+        params: { spaceId: string; revisionId: string; metadata: boolean }
+    ) => {
+        'use cache';
+        return trace(`getRevisionPages(${params.spaceId}, ${params.revisionId})`, async () => {
+            return wrapDataFetcherError(async () => {
+                const api = apiClient(input);
+                const res = await api.spaces.listPagesInRevisionById(
+                    params.spaceId,
+                    params.revisionId,
+                    {
+                        metadata: params.metadata,
+                    },
+                    {
+                        ...noCacheFetchOptions,
+                    }
+                );
+                cacheTag(...getCacheTagsFromResponse(res));
+                cacheLife('max');
+                return res.data.pages;
+            });
+        });
+    }
+);
+
+const getRevisionFile = cache(
+    async (
+        input: DataFetcherInput,
+        params: { spaceId: string; revisionId: string; fileId: string }
+    ) => {
+        'use cache';
+        return trace(
+            `getRevisionFile(${params.spaceId}, ${params.revisionId}, ${params.fileId})`,
+            async () => {
                 return wrapDataFetcherError(async () => {
                     const api = apiClient(input);
-                    const res = await api.spaces.getRevisionById(
+                    const res = await api.spaces.getFileInRevisionById(
                         params.spaceId,
                         params.revisionId,
-                        {
-                            metadata: params.metadata,
-                        },
-                        {
-                            ...noCacheFetchOptions,
-                        }
-                    );
-                    cacheTag(...getCacheTagsFromResponse(res));
-                    cacheLife('max');
-                    return res.data;
-                });
-            });
-        }
-    )
-);
-
-const getRevisionPages = withCacheKey(
-    withoutConcurrentExecution(
-        async (
-            _,
-            input: DataFetcherInput,
-            params: { spaceId: string; revisionId: string; metadata: boolean }
-        ) => {
-            'use cache';
-            return trace(`getRevisionPages(${params.spaceId}, ${params.revisionId})`, async () => {
-                return wrapDataFetcherError(async () => {
-                    const api = apiClient(input);
-                    const res = await api.spaces.listPagesInRevisionById(
-                        params.spaceId,
-                        params.revisionId,
-                        {
-                            metadata: params.metadata,
-                        },
-                        {
-                            ...noCacheFetchOptions,
-                        }
-                    );
-                    cacheTag(...getCacheTagsFromResponse(res));
-                    cacheLife('max');
-                    return res.data.pages;
-                });
-            });
-        }
-    )
-);
-
-const getRevisionFile = withCacheKey(
-    withoutConcurrentExecution(
-        async (
-            _,
-            input: DataFetcherInput,
-            params: { spaceId: string; revisionId: string; fileId: string }
-        ) => {
-            'use cache';
-            return trace(
-                `getRevisionFile(${params.spaceId}, ${params.revisionId}, ${params.fileId})`,
-                async () => {
-                    return wrapDataFetcherError(async () => {
-                        const api = apiClient(input);
-                        const res = await api.spaces.getFileInRevisionById(
-                            params.spaceId,
-                            params.revisionId,
-                            params.fileId,
-                            {},
-                            {
-                                ...noCacheFetchOptions,
-                            }
-                        );
-                        cacheTag(...getCacheTagsFromResponse(res));
-                        cacheLife('max');
-                        return res.data;
-                    });
-                }
-            );
-        }
-    )
-);
-
-const getRevisionPageMarkdown = withCacheKey(
-    withoutConcurrentExecution(
-        async (
-            _,
-            input: DataFetcherInput,
-            params: { spaceId: string; revisionId: string; pageId: string }
-        ) => {
-            'use cache';
-            return trace(
-                `getRevisionPageMarkdown(${params.spaceId}, ${params.revisionId}, ${params.pageId})`,
-                async () => {
-                    return wrapDataFetcherError(async () => {
-                        const api = apiClient(input);
-                        const res = await api.spaces.getPageInRevisionById(
-                            params.spaceId,
-                            params.revisionId,
-                            params.pageId,
-                            {
-                                format: 'markdown',
-                            },
-                            {
-                                ...noCacheFetchOptions,
-                            }
-                        );
-
-                        cacheTag(...getCacheTagsFromResponse(res));
-                        cacheLife('max');
-
-                        if (!('markdown' in res.data)) {
-                            throw new DataFetcherError('Page is not a document', 404);
-                        }
-                        return res.data.markdown;
-                    });
-                }
-            );
-        }
-    )
-);
-
-const getRevisionPageDocument = withCacheKey(
-    withoutConcurrentExecution(
-        async (
-            _,
-            input: DataFetcherInput,
-            params: { spaceId: string; revisionId: string; pageId: string }
-        ) => {
-            'use cache';
-            return trace(
-                `getRevisionPageDocument(${params.spaceId}, ${params.revisionId}, ${params.pageId})`,
-                async () => {
-                    return wrapDataFetcherError(async () => {
-                        const api = apiClient(input);
-                        const res = await api.spaces.getPageDocumentInRevisionById(
-                            params.spaceId,
-                            params.revisionId,
-                            params.pageId,
-                            {
-                                evaluated: true,
-                            },
-                            {
-                                ...noCacheFetchOptions,
-                            }
-                        );
-
-                        cacheTag(...getCacheTagsFromResponse(res));
-                        cacheLife('max');
-
-                        return res.data;
-                    });
-                }
-            );
-        }
-    )
-);
-
-const getRevisionPageByPath = withCacheKey(
-    withoutConcurrentExecution(
-        async (
-            _,
-            input: DataFetcherInput,
-            params: { spaceId: string; revisionId: string; path: string }
-        ) => {
-            'use cache';
-            return trace(
-                `getRevisionPageByPath(${params.spaceId}, ${params.revisionId}, ${params.path})`,
-                async () => {
-                    const encodedPath = encodeURIComponent(params.path);
-                    return wrapDataFetcherError(async () => {
-                        const api = apiClient(input);
-                        const res = await api.spaces.getPageInRevisionByPath(
-                            params.spaceId,
-                            params.revisionId,
-                            encodedPath,
-                            {},
-                            {
-                                ...noCacheFetchOptions,
-                            }
-                        );
-                        cacheTag(...getCacheTagsFromResponse(res));
-                        cacheLife('max');
-                        return res.data;
-                    });
-                }
-            );
-        }
-    )
-);
-
-const getDocument = withCacheKey(
-    withoutConcurrentExecution(
-        async (_, input: DataFetcherInput, params: { spaceId: string; documentId: string }) => {
-            'use cache';
-            return trace(`getDocument(${params.spaceId}, ${params.documentId})`, async () => {
-                return wrapDataFetcherError(async () => {
-                    const api = apiClient(input);
-                    const res = await api.spaces.getDocumentById(
-                        params.spaceId,
-                        params.documentId,
+                        params.fileId,
                         {},
                         {
                             ...noCacheFetchOptions,
@@ -514,308 +356,263 @@ const getDocument = withCacheKey(
                     cacheLife('max');
                     return res.data;
                 });
-            });
-        }
-    )
-);
-
-const getComputedDocument = withCacheKey(
-    withoutConcurrentExecution(
-        async (
-            _,
-            input: DataFetcherInput,
-            params: {
-                spaceId: string;
-                organizationId: string;
-                source: ComputedContentSource;
-                seed: string;
             }
-        ) => {
-            'use cache';
-            cacheTag(
-                ...getComputedContentSourceCacheTags(
-                    {
-                        spaceId: params.spaceId,
-                        organizationId: params.organizationId,
-                    },
-                    params.source
-                )
-            );
-
-            return trace(
-                `getComputedDocument(${params.spaceId}, ${params.organizationId}, ${params.source.type}, ${params.seed})`,
-                async () => {
-                    return wrapDataFetcherError(async () => {
-                        const api = apiClient(input);
-                        const res = await api.spaces.getComputedDocument(
-                            params.spaceId,
-                            {
-                                source: params.source,
-                                seed: params.seed,
-                            },
-                            {},
-                            {
-                                ...noCacheFetchOptions,
-                            }
-                        );
-                        cacheTag(...getCacheTagsFromResponse(res));
-                        cacheLife('max');
-                        return res.data;
-                    });
-                }
-            );
-        }
-    )
+        );
+    }
 );
 
-const getReusableContent = withCacheKey(
-    withoutConcurrentExecution(
-        async (
-            _,
-            input: DataFetcherInput,
-            params: { spaceId: string; revisionId: string; reusableContentId: string }
-        ) => {
-            'use cache';
-            return trace(
-                `getReusableContent(${params.spaceId}, ${params.revisionId}, ${params.reusableContentId})`,
-                async () => {
-                    return wrapDataFetcherError(async () => {
-                        const api = apiClient(input);
-                        const res = await api.spaces.getReusableContentInRevisionById(
-                            params.spaceId,
-                            params.revisionId,
-                            params.reusableContentId,
-                            {},
-                            {
-                                ...noCacheFetchOptions,
-                            }
-                        );
-                        cacheTag(...getCacheTagsFromResponse(res));
-                        cacheLife('max');
-                        return res.data;
-                    });
-                }
-            );
-        }
-    )
-);
-
-const getLatestOpenAPISpecVersionContent = withCacheKey(
-    withoutConcurrentExecution(
-        async (_, input: DataFetcherInput, params: { organizationId: string; slug: string }) => {
-            'use cache';
-            cacheTag(
-                getCacheTag({
-                    tag: 'openapi',
-                    organization: params.organizationId,
-                    openAPISpec: params.slug,
-                })
-            );
-
-            return trace(
-                `getLatestOpenAPISpecVersionContent(${params.organizationId}, ${params.slug})`,
-                async () => {
-                    return wrapDataFetcherError(async () => {
-                        const api = apiClient(input);
-                        const res = await api.orgs.getLatestOpenApiSpecVersionContent(
-                            params.organizationId,
-                            params.slug,
-                            {
-                                ...noCacheFetchOptions,
-                            }
-                        );
-                        cacheTag(...getCacheTagsFromResponse(res));
-                        cacheLife('max');
-                        return res.data;
-                    });
-                }
-            );
-        }
-    )
-);
-
-const getPublishedContentSite = withCacheKey(
-    withoutConcurrentExecution(
-        async (
-            _,
-            input: DataFetcherInput,
-            params: { organizationId: string; siteId: string; siteShareKey: string | undefined }
-        ) => {
-            'use cache';
-            cacheTag(
-                getCacheTag({
-                    tag: 'site',
-                    site: params.siteId,
-                })
-            );
-
-            return trace(
-                `getPublishedContentSite(${params.organizationId}, ${params.siteId}, ${params.siteShareKey})`,
-                async () => {
-                    return wrapDataFetcherError(async () => {
-                        const api = apiClient(input);
-                        const res = await api.orgs.getPublishedContentSite(
-                            params.organizationId,
-                            params.siteId,
-                            {
-                                shareKey: params.siteShareKey,
-                            },
-                            {
-                                ...noCacheFetchOptions,
-                            }
-                        );
-                        cacheTag(...getCacheTagsFromResponse(res));
-                        cacheLife('days');
-                        return res.data;
-                    });
-                }
-            );
-        }
-    )
-);
-
-const getSiteRedirectBySource = withCacheKey(
-    withoutConcurrentExecution(
-        async (
-            _,
-            input: DataFetcherInput,
-            params: {
-                organizationId: string;
-                siteId: string;
-                siteShareKey: string | undefined;
-                source: string;
-            }
-        ) => {
-            'use cache';
-            cacheTag(
-                getCacheTag({
-                    tag: 'site',
-                    site: params.siteId,
-                })
-            );
-
-            return trace(
-                `getSiteRedirectBySource(${params.organizationId}, ${params.siteId}, ${params.siteShareKey}, ${params.source})`,
-                async () => {
-                    return wrapDataFetcherError(async () => {
-                        const api = apiClient(input);
-                        const res = await api.orgs.getSiteRedirectBySource(
-                            params.organizationId,
-                            params.siteId,
-                            {
-                                shareKey: params.siteShareKey,
-                                source: params.source,
-                            },
-                            {
-                                ...noCacheFetchOptions,
-                            }
-                        );
-                        cacheTag(...getCacheTagsFromResponse(res));
-                        cacheLife('days');
-                        return res.data;
-                    });
-                }
-            );
-        }
-    )
-);
-
-const getEmbedByUrl = withCacheKey(
-    withoutConcurrentExecution(
-        async (_, input: DataFetcherInput, params: { spaceId: string; url: string }) => {
-            'use cache';
-            cacheTag(
-                getCacheTag({
-                    tag: 'space',
-                    space: params.spaceId,
-                })
-            );
-
-            return trace(`getEmbedByUrl(${params.spaceId}, ${params.url})`, async () => {
+const getRevisionPageMarkdown = cache(
+    async (
+        input: DataFetcherInput,
+        params: { spaceId: string; revisionId: string; pageId: string }
+    ) => {
+        'use cache';
+        return trace(
+            `getRevisionPageMarkdown(${params.spaceId}, ${params.revisionId}, ${params.pageId})`,
+            async () => {
                 return wrapDataFetcherError(async () => {
                     const api = apiClient(input);
-                    const res = await api.spaces.getEmbedByUrlInSpace(
+                    const res = await api.spaces.getPageInRevisionById(
                         params.spaceId,
+                        params.revisionId,
+                        params.pageId,
                         {
-                            url: params.url,
+                            format: 'markdown',
                         },
                         {
                             ...noCacheFetchOptions,
                         }
                     );
+
                     cacheTag(...getCacheTagsFromResponse(res));
-                    cacheLife('weeks');
-                    return res.data;
+                    cacheLife('max');
+
+                    if (!('markdown' in res.data)) {
+                        throw new DataFetcherError('Page is not a document', 404);
+                    }
+                    return res.data.markdown;
                 });
-            });
-        }
-    )
+            }
+        );
+    }
 );
 
-const searchSiteContent = withCacheKey(
-    withoutConcurrentExecution(
-        async (
-            _,
-            input: DataFetcherInput,
-            params: Parameters<GitBookDataFetcher['searchSiteContent']>[0]
-        ) => {
-            'use cache';
-            cacheTag(
-                getCacheTag({
-                    tag: 'site',
-                    site: params.siteId,
-                })
-            );
-
-            return trace(
-                `searchSiteContent(${params.organizationId}, ${params.siteId}, ${params.query})`,
-                async () => {
-                    return wrapDataFetcherError(async () => {
-                        const { organizationId, siteId, query, scope } = params;
-                        const api = apiClient(input);
-                        const res = await api.orgs.searchSiteContent(
-                            organizationId,
-                            siteId,
-                            {
-                                query,
-                                ...scope,
-                            },
-                            {},
-                            {
-                                ...noCacheFetchOptions,
-                            }
-                        );
-                        cacheTag(...getCacheTagsFromResponse(res));
-                        cacheLife('hours');
-                        return res.data.items;
-                    });
-                }
-            );
-        }
-    )
-);
-
-const renderIntegrationUi = withCacheKey(
-    withoutConcurrentExecution(
-        async (
-            _,
-            input: DataFetcherInput,
-            params: { integrationName: string; request: RenderIntegrationUI }
-        ) => {
-            'use cache';
-            cacheTag(
-                getCacheTag({
-                    tag: 'integration',
-                    integration: params.integrationName,
-                })
-            );
-
-            return trace(`renderIntegrationUi(${params.integrationName})`, async () => {
+const getRevisionPageDocument = cache(
+    async (
+        input: DataFetcherInput,
+        params: { spaceId: string; revisionId: string; pageId: string }
+    ) => {
+        'use cache';
+        return trace(
+            `getRevisionPageDocument(${params.spaceId}, ${params.revisionId}, ${params.pageId})`,
+            async () => {
                 return wrapDataFetcherError(async () => {
                     const api = apiClient(input);
-                    const res = await api.integrations.renderIntegrationUiWithPost(
-                        params.integrationName,
-                        params.request,
+                    const res = await api.spaces.getPageDocumentInRevisionById(
+                        params.spaceId,
+                        params.revisionId,
+                        params.pageId,
+                        {
+                            evaluated: true,
+                        },
+                        {
+                            ...noCacheFetchOptions,
+                        }
+                    );
+
+                    cacheTag(...getCacheTagsFromResponse(res));
+                    cacheLife('max');
+
+                    return res.data;
+                });
+            }
+        );
+    }
+);
+
+const getRevisionPageByPath = cache(
+    async (
+        input: DataFetcherInput,
+        params: { spaceId: string; revisionId: string; path: string }
+    ) => {
+        'use cache';
+        return trace(
+            `getRevisionPageByPath(${params.spaceId}, ${params.revisionId}, ${params.path})`,
+            async () => {
+                const encodedPath = encodeURIComponent(params.path);
+                return wrapDataFetcherError(async () => {
+                    const api = apiClient(input);
+                    const res = await api.spaces.getPageInRevisionByPath(
+                        params.spaceId,
+                        params.revisionId,
+                        encodedPath,
+                        {},
+                        {
+                            ...noCacheFetchOptions,
+                        }
+                    );
+                    cacheTag(...getCacheTagsFromResponse(res));
+                    cacheLife('max');
+                    return res.data;
+                });
+            }
+        );
+    }
+);
+
+const getDocument = cache(
+    async (input: DataFetcherInput, params: { spaceId: string; documentId: string }) => {
+        'use cache';
+        return trace(`getDocument(${params.spaceId}, ${params.documentId})`, async () => {
+            return wrapDataFetcherError(async () => {
+                const api = apiClient(input);
+                const res = await api.spaces.getDocumentById(
+                    params.spaceId,
+                    params.documentId,
+                    {},
+                    {
+                        ...noCacheFetchOptions,
+                    }
+                );
+                cacheTag(...getCacheTagsFromResponse(res));
+                cacheLife('max');
+                return res.data;
+            });
+        });
+    }
+);
+
+const getComputedDocument = cache(
+    async (
+        input: DataFetcherInput,
+        params: {
+            spaceId: string;
+            organizationId: string;
+            source: ComputedContentSource;
+            seed: string;
+        }
+    ) => {
+        'use cache';
+        cacheTag(
+            ...getComputedContentSourceCacheTags(
+                {
+                    spaceId: params.spaceId,
+                    organizationId: params.organizationId,
+                },
+                params.source
+            )
+        );
+
+        return trace(
+            `getComputedDocument(${params.spaceId}, ${params.organizationId}, ${params.source.type}, ${params.seed})`,
+            async () => {
+                return wrapDataFetcherError(async () => {
+                    const api = apiClient(input);
+                    const res = await api.spaces.getComputedDocument(
+                        params.spaceId,
+                        {
+                            source: params.source,
+                            seed: params.seed,
+                        },
+                        {},
+                        {
+                            ...noCacheFetchOptions,
+                        }
+                    );
+                    cacheTag(...getCacheTagsFromResponse(res));
+                    cacheLife('max');
+                    return res.data;
+                });
+            }
+        );
+    }
+);
+
+const getReusableContent = cache(
+    async (
+        input: DataFetcherInput,
+        params: { spaceId: string; revisionId: string; reusableContentId: string }
+    ) => {
+        'use cache';
+        return trace(
+            `getReusableContent(${params.spaceId}, ${params.revisionId}, ${params.reusableContentId})`,
+            async () => {
+                return wrapDataFetcherError(async () => {
+                    const api = apiClient(input);
+                    const res = await api.spaces.getReusableContentInRevisionById(
+                        params.spaceId,
+                        params.revisionId,
+                        params.reusableContentId,
+                        {},
+                        {
+                            ...noCacheFetchOptions,
+                        }
+                    );
+                    cacheTag(...getCacheTagsFromResponse(res));
+                    cacheLife('max');
+                    return res.data;
+                });
+            }
+        );
+    }
+);
+
+const getLatestOpenAPISpecVersionContent = cache(
+    async (input: DataFetcherInput, params: { organizationId: string; slug: string }) => {
+        'use cache';
+        cacheTag(
+            getCacheTag({
+                tag: 'openapi',
+                organization: params.organizationId,
+                openAPISpec: params.slug,
+            })
+        );
+
+        return trace(
+            `getLatestOpenAPISpecVersionContent(${params.organizationId}, ${params.slug})`,
+            async () => {
+                return wrapDataFetcherError(async () => {
+                    const api = apiClient(input);
+                    const res = await api.orgs.getLatestOpenApiSpecVersionContent(
+                        params.organizationId,
+                        params.slug,
+                        {
+                            ...noCacheFetchOptions,
+                        }
+                    );
+                    cacheTag(...getCacheTagsFromResponse(res));
+                    cacheLife('max');
+                    return res.data;
+                });
+            }
+        );
+    }
+);
+
+const getPublishedContentSite = cache(
+    async (
+        input: DataFetcherInput,
+        params: { organizationId: string; siteId: string; siteShareKey: string | undefined }
+    ) => {
+        'use cache';
+        cacheTag(
+            getCacheTag({
+                tag: 'site',
+                site: params.siteId,
+            })
+        );
+
+        return trace(
+            `getPublishedContentSite(${params.organizationId}, ${params.siteId}, ${params.siteShareKey})`,
+            async () => {
+                return wrapDataFetcherError(async () => {
+                    const api = apiClient(input);
+                    const res = await api.orgs.getPublishedContentSite(
+                        params.organizationId,
+                        params.siteId,
+                        {
+                            shareKey: params.siteShareKey,
+                        },
                         {
                             ...noCacheFetchOptions,
                         }
@@ -824,9 +621,153 @@ const renderIntegrationUi = withCacheKey(
                     cacheLife('days');
                     return res.data;
                 });
-            });
+            }
+        );
+    }
+);
+
+const getSiteRedirectBySource = cache(
+    async (
+        input: DataFetcherInput,
+        params: {
+            organizationId: string;
+            siteId: string;
+            siteShareKey: string | undefined;
+            source: string;
         }
-    )
+    ) => {
+        'use cache';
+        cacheTag(
+            getCacheTag({
+                tag: 'site',
+                site: params.siteId,
+            })
+        );
+
+        return trace(
+            `getSiteRedirectBySource(${params.organizationId}, ${params.siteId}, ${params.siteShareKey}, ${params.source})`,
+            async () => {
+                return wrapDataFetcherError(async () => {
+                    const api = apiClient(input);
+                    const res = await api.orgs.getSiteRedirectBySource(
+                        params.organizationId,
+                        params.siteId,
+                        {
+                            shareKey: params.siteShareKey,
+                            source: params.source,
+                        },
+                        {
+                            ...noCacheFetchOptions,
+                        }
+                    );
+                    cacheTag(...getCacheTagsFromResponse(res));
+                    cacheLife('days');
+                    return res.data;
+                });
+            }
+        );
+    }
+);
+
+const getEmbedByUrl = cache(
+    async (input: DataFetcherInput, params: { spaceId: string; url: string }) => {
+        'use cache';
+        cacheTag(
+            getCacheTag({
+                tag: 'space',
+                space: params.spaceId,
+            })
+        );
+
+        return trace(`getEmbedByUrl(${params.spaceId}, ${params.url})`, async () => {
+            return wrapDataFetcherError(async () => {
+                const api = apiClient(input);
+                const res = await api.spaces.getEmbedByUrlInSpace(
+                    params.spaceId,
+                    {
+                        url: params.url,
+                    },
+                    {
+                        ...noCacheFetchOptions,
+                    }
+                );
+                cacheTag(...getCacheTagsFromResponse(res));
+                cacheLife('weeks');
+                return res.data;
+            });
+        });
+    }
+);
+
+const searchSiteContent = cache(
+    async (
+        input: DataFetcherInput,
+        params: Parameters<GitBookDataFetcher['searchSiteContent']>[0]
+    ) => {
+        'use cache';
+        cacheTag(
+            getCacheTag({
+                tag: 'site',
+                site: params.siteId,
+            })
+        );
+
+        return trace(
+            `searchSiteContent(${params.organizationId}, ${params.siteId}, ${params.query})`,
+            async () => {
+                return wrapDataFetcherError(async () => {
+                    const { organizationId, siteId, query, scope } = params;
+                    const api = apiClient(input);
+                    const res = await api.orgs.searchSiteContent(
+                        organizationId,
+                        siteId,
+                        {
+                            query,
+                            ...scope,
+                        },
+                        {},
+                        {
+                            ...noCacheFetchOptions,
+                        }
+                    );
+                    cacheTag(...getCacheTagsFromResponse(res));
+                    cacheLife('hours');
+                    return res.data.items;
+                });
+            }
+        );
+    }
+);
+
+const renderIntegrationUi = cache(
+    async (
+        input: DataFetcherInput,
+        params: { integrationName: string; request: RenderIntegrationUI }
+    ) => {
+        'use cache';
+        cacheTag(
+            getCacheTag({
+                tag: 'integration',
+                integration: params.integrationName,
+            })
+        );
+
+        return trace(`renderIntegrationUi(${params.integrationName})`, async () => {
+            return wrapDataFetcherError(async () => {
+                const api = apiClient(input);
+                const res = await api.integrations.renderIntegrationUiWithPost(
+                    params.integrationName,
+                    params.request,
+                    {
+                        ...noCacheFetchOptions,
+                    }
+                );
+                cacheTag(...getCacheTagsFromResponse(res));
+                cacheLife('days');
+                return res.data;
+            });
+        });
+    }
 );
 
 async function* streamAIResponse(
diff --git a/packages/gitbook-v2/src/lib/data/memoize.ts b/packages/gitbook-v2/src/lib/data/memoize.ts
deleted file mode 100644
index 5110d015f..000000000
--- a/packages/gitbook-v2/src/lib/data/memoize.ts
+++ /dev/null
@@ -1,92 +0,0 @@
-import { cache } from 'react';
-
-// This is used to create a context specific to the current request.
-// This version works both in cloudflare and in vercel.
-const getRequestContext = cache(() => ({}));
-
-/**
- * Wrap a function by preventing concurrent executions of the same function.
- * With a logic to work per-request in Cloudflare Workers.
- */
-export function withoutConcurrentExecution<ArgsType extends any[], ReturnType>(
-    wrapped: (key: string, ...args: ArgsType) => Promise<ReturnType>
-): (cacheKey: string, ...args: ArgsType) => Promise<ReturnType> {
-    const globalPromiseCache = new WeakMap<object, Map<string, Promise<ReturnType>>>();
-
-    return (key: string, ...args: ArgsType) => {
-        const globalContext = getRequestContext();
-
-        /**
-         * Cache storage that is scoped to the current request when executed in Cloudflare Workers,
-         * to avoid "Cannot perform I/O on behalf of a different request" errors.
-         */
-        const promiseCache =
-            globalPromiseCache.get(globalContext) ?? new Map<string, Promise<ReturnType>>();
-        globalPromiseCache.set(globalContext, promiseCache);
-
-        const concurrent = promiseCache.get(key);
-        if (concurrent) {
-            return concurrent;
-        }
-
-        const promise = (async () => {
-            try {
-                const result = await wrapped(key, ...args);
-                return result;
-            } finally {
-                promiseCache.delete(key);
-            }
-        })();
-
-        promiseCache.set(key, promise);
-
-        return promise;
-    };
-}
-
-/**
- * Wrap a function by passing it a cache key that is computed from the function arguments.
- */
-export function withCacheKey<ArgsType extends any[], ReturnType>(
-    wrapped: (cacheKey: string, ...args: ArgsType) => Promise<ReturnType>
-): (...args: ArgsType) => Promise<ReturnType> {
-    return (...args: ArgsType) => {
-        const cacheKey = getCacheKey(args);
-        return wrapped(cacheKey, ...args);
-    };
-}
-
-/**
- * Compute a cache key from the function arguments.
- */
-function getCacheKey(args: any[]) {
-    return JSON.stringify(deepSortValue(args));
-}
-
-function deepSortValue(value: unknown): unknown {
-    if (
-        typeof value === 'string' ||
-        typeof value === 'number' ||
-        typeof value === 'boolean' ||
-        value === null ||
-        value === undefined
-    ) {
-        return value;
-    }
-
-    if (Array.isArray(value)) {
-        return value.map(deepSortValue);
-    }
-
-    if (value && typeof value === 'object') {
-        return Object.entries(value)
-            .map(([key, subValue]) => {
-                return [key, deepSortValue(subValue)] as const;
-            })
-            .sort((a, b) => {
-                return a[0].localeCompare(b[0]);
-            });
-    }
-
-    return value;
-}

From d99da6a3ae7f128116bbec9ade8dcbe01f94eb31 Mon Sep 17 00:00:00 2001
From: Utku Ufuk <utkuufuk@gmail.com>
Date: Mon, 16 Jun 2025 14:33:00 +0200
Subject: [PATCH 08/23] Ignore case while pattern-matching to highlight search
 results (#3326)

---
 .changeset/slimy-cows-press.md                               | 5 +++++
 .../src/components/Search/SearchSectionResultItem.tsx        | 4 ++--
 2 files changed, 7 insertions(+), 2 deletions(-)
 create mode 100644 .changeset/slimy-cows-press.md

diff --git a/.changeset/slimy-cows-press.md b/.changeset/slimy-cows-press.md
new file mode 100644
index 000000000..17ec44ca8
--- /dev/null
+++ b/.changeset/slimy-cows-press.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Ignore case while highlighting search results.
diff --git a/packages/gitbook/src/components/Search/SearchSectionResultItem.tsx b/packages/gitbook/src/components/Search/SearchSectionResultItem.tsx
index a0f467f80..8ccda684d 100644
--- a/packages/gitbook/src/components/Search/SearchSectionResultItem.tsx
+++ b/packages/gitbook/src/components/Search/SearchSectionResultItem.tsx
@@ -88,12 +88,12 @@ export const SearchSectionResultItem = React.forwardRef(function SearchSectionRe
 });
 
 function highlightQueryInBody(body: string, query: string) {
-    const idx = body.indexOf(query);
+    const idx = body.toLocaleLowerCase().indexOf(query.toLocaleLowerCase());
 
     // Ensure the query to be highlighted is visible in the body.
     return (
         <p className={tcls('text-sm', 'line-clamp-3', 'relative')}>
-            <HighlightQuery query={query} text={idx < 20 ? body : `...${body.slice(idx - 15)}`} />
+            <HighlightQuery query={query} text={idx < 20 ? body : `...${body.slice(idx - 10)}`} />
         </p>
     );
 }

From 382a19885be802945ee309e71d4699ccd720c94f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Greg=20Berg=C3=A9?= <berge.greg@gmail.com>
Date: Mon, 16 Jun 2025 15:52:42 +0200
Subject: [PATCH 09/23] Hide empty section groups (#3327)

---
 .../SiteSections/encodeClientSiteSections.ts  | 37 +++++++++++++------
 1 file changed, 25 insertions(+), 12 deletions(-)

diff --git a/packages/gitbook/src/components/SiteSections/encodeClientSiteSections.ts b/packages/gitbook/src/components/SiteSections/encodeClientSiteSections.ts
index 891936b6f..98c22bbb6 100644
--- a/packages/gitbook/src/components/SiteSections/encodeClientSiteSections.ts
+++ b/packages/gitbook/src/components/SiteSections/encodeClientSiteSections.ts
@@ -1,6 +1,7 @@
 import { getSectionURL, getSiteSpaceURL } from '@/lib/sites';
 import type { SiteSection, SiteSectionGroup, SiteSpace } from '@gitbook/api';
 import type { GitBookSiteContext, SiteSections } from '@v2/lib/context';
+import assertNever from 'assert-never';
 
 export type ClientSiteSections = {
     list: (ClientSiteSection | ClientSiteSectionGroup)[];
@@ -27,20 +28,32 @@ export function encodeClientSiteSections(context: GitBookSiteContext, sections:
     const clientSections: (ClientSiteSection | ClientSiteSectionGroup)[] = [];
 
     for (const item of list) {
-        if (item.object === 'site-section-group') {
-            clientSections.push({
-                id: item.id,
-                title: item.title,
-                icon: item.icon,
-                object: item.object,
-                sections: item.sections
+        switch (item.object) {
+            case 'site-section-group': {
+                const sections = item.sections
                     .filter((section) => shouldIncludeSection(context, section))
-                    .map((section) => encodeSection(context, section)),
-            });
-        } else {
-            if (shouldIncludeSection(context, item)) {
-                clientSections.push(encodeSection(context, item));
+                    .map((section) => encodeSection(context, section));
+
+                // Skip empty groups
+                if (sections.length === 0) {
+                    continue;
+                }
+
+                clientSections.push({
+                    id: item.id,
+                    title: item.title,
+                    icon: item.icon,
+                    object: item.object,
+                    sections,
+                });
+                continue;
             }
+            case 'site-section': {
+                clientSections.push(encodeSection(context, item));
+                continue;
+            }
+            default:
+                assertNever(item, 'Unknown site section object type');
         }
     }
 

From b7a0db3339dcdfb882a5e46e90a989bb1eb088a0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Samy=20Pess=C3=A9?= <samypesse@gmail.com>
Date: Mon, 16 Jun 2025 16:59:54 +0200
Subject: [PATCH 10/23] Fix rendering of ogimage with SVG logos (#3328)

---
 .changeset/green-clouds-cough.md        |  5 ++
 bun.lock                                |  3 +
 packages/gitbook/package.json           |  3 +-
 packages/gitbook/src/routes/ogimage.tsx | 85 +++++++++++--------------
 4 files changed, 48 insertions(+), 48 deletions(-)
 create mode 100644 .changeset/green-clouds-cough.md

diff --git a/.changeset/green-clouds-cough.md b/.changeset/green-clouds-cough.md
new file mode 100644
index 000000000..098860381
--- /dev/null
+++ b/.changeset/green-clouds-cough.md
@@ -0,0 +1,5 @@
+---
+"gitbook": minor
+---
+
+Fix rendering of ogimage with SVG logos.
diff --git a/bun.lock b/bun.lock
index b4d2b49d1..1c192ca71 100644
--- a/bun.lock
+++ b/bun.lock
@@ -87,6 +87,7 @@
         "classnames": "^2.5.1",
         "event-iterator": "^2.0.0",
         "framer-motion": "^10.16.14",
+        "image-size": "^2.0.2",
         "js-cookie": "^3.0.5",
         "jsontoxml": "^1.0.1",
         "jwt-decode": "^4.0.0",
@@ -2067,6 +2068,8 @@
 
     "ignore": ["ignore@7.0.3", "", {}, "sha512-bAH5jbK/F3T3Jls4I0SO1hmPR0dKU0a7+SY6n1yzRtG54FLO8d6w/nxLFX2Nb7dBu6cCWXPaAME6cYqFUMmuCA=="],
 
+    "image-size": ["image-size@2.0.2", "", { "bin": { "image-size": "bin/image-size.js" } }, "sha512-IRqXKlaXwgSMAMtpNzZa1ZAe8m+Sa1770Dhk8VkSsP9LS+iHD62Zd8FQKs8fbPiagBE7BzoFX23cxFnwshpV6w=="],
+
     "import-fresh": ["import-fresh@3.3.1", "", { "dependencies": { "parent-module": "^1.0.0", "resolve-from": "^4.0.0" } }, "sha512-TR3KfrTZTYLPB6jUjfx6MF9WcWrHL9su5TObK4ZkYgBdWKPOFoSoQIdEuTuR82pmtxH2spWG9h6etwfr1pLBqQ=="],
 
     "import-lazy": ["import-lazy@2.1.0", "", {}, "sha512-m7ZEHgtw69qOGw+jwxXkHlrlIPdTGkyh66zXZ1ajZbxkDBNjSY/LGbmjc7h0s2ELsUDTAhFr55TrPSSqJGPG0A=="],
diff --git a/packages/gitbook/package.json b/packages/gitbook/package.json
index 379f975a1..2be76259d 100644
--- a/packages/gitbook/package.json
+++ b/packages/gitbook/package.json
@@ -81,7 +81,8 @@
         "usehooks-ts": "^3.1.0",
         "zod": "^3.24.2",
         "zod-to-json-schema": "^3.24.5",
-        "zustand": "^5.0.3"
+        "zustand": "^5.0.3",
+        "image-size": "^2.0.2"
     },
     "devDependencies": {
         "@argos-ci/playwright": "^5.0.3",
diff --git a/packages/gitbook/src/routes/ogimage.tsx b/packages/gitbook/src/routes/ogimage.tsx
index e213ee223..653fc8fc3 100644
--- a/packages/gitbook/src/routes/ogimage.tsx
+++ b/packages/gitbook/src/routes/ogimage.tsx
@@ -1,6 +1,7 @@
 import { CustomizationDefaultFont, CustomizationHeaderPreset } from '@gitbook/api';
 import { colorContrast } from '@gitbook/colors';
 import { type FontWeight, getDefaultFont } from '@gitbook/fonts';
+import { imageSize } from 'image-size';
 import { redirect } from 'next/navigation';
 import { ImageResponse } from 'next/og';
 
@@ -156,14 +157,14 @@ export async function serveOGImage(baseContext: GitBookSiteContext, params: Page
                     {String.fromCodePoint(Number.parseInt(`0x${customization.favicon.emoji}`))}
                 </span>
             );
-        const src = await readSelfImage(
+        const iconImage = await fetchImage(
             linker.toAbsoluteURL(
                 linker.toPathInSpace(
                     `~gitbook/icon?size=medium&theme=${customization.themes.default}`
                 )
             )
         );
-        return <img src={src} alt="Icon" width={40} height={40} tw="mr-4" />;
+        return <img {...iconImage} alt="Icon" width={40} height={40} tw="mr-4" />;
     };
 
     const [favicon, { fontFamily, fonts }] = await Promise.all([faviconLoader(), fontLoader()]);
@@ -187,21 +188,23 @@ export async function serveOGImage(baseContext: GitBookSiteContext, params: Page
             {/* Grid */}
             <img
                 tw="absolute inset-0 w-[100vw] h-[100vh]"
-                src={await readStaticImage(gridAsset)}
+                src={(await fetchStaticImage(gridAsset)).src}
                 alt="Grid"
             />
 
             {/* Logo */}
             {customization.header.logo ? (
-                <img
-                    alt="Logo"
-                    height={60}
-                    src={
-                        useLightTheme
-                            ? customization.header.logo.light
-                            : customization.header.logo.dark
-                    }
-                />
+                <div tw="flex flex-row">
+                    <img
+                        {...(await fetchImage(
+                            useLightTheme
+                                ? customization.header.logo.light
+                                : customization.header.logo.dark
+                        ))}
+                        alt="Logo"
+                        tw="h-[60px]"
+                    />
+                </div>
             ) : (
                 <div tw="flex">
                     {favicon}
@@ -289,34 +292,6 @@ async function loadCustomFont(input: { url: string; weight: 400 | 700 }) {
     };
 }
 
-/**
- * Temporary function to log some data on Cloudflare.
- * TODO: remove this when we found the issue
- */
-function logOnCloudflareOnly(message: string) {
-    if (process.env.DEBUG_CLOUDFLARE === 'true') {
-        // biome-ignore lint/suspicious/noConsole: <explanation>
-        console.log(message);
-    }
-}
-
-/**
- * Read an image from a response as a base64 encoded string.
- */
-async function readImage(response: Response) {
-    const contentType = response.headers.get('content-type');
-    if (!contentType || !contentType.startsWith('image/')) {
-        logOnCloudflareOnly(`Invalid content type: ${contentType}, 
-            status: ${response.status}
-            rayId: ${response.headers.get('cf-ray')}`);
-        throw new Error(`Invalid content type: ${contentType}`);
-    }
-
-    const arrayBuffer = await response.arrayBuffer();
-    const base64 = Buffer.from(arrayBuffer).toString('base64');
-    return `data:${contentType};base64,${base64}`;
-}
-
 // biome-ignore lint/suspicious/noExplicitAny: <explanation>
 const staticCache = new Map<string, any>();
 
@@ -335,16 +310,32 @@ async function getWithCache<T>(key: string, fn: () => Promise<T>) {
 /**
  * Read a static image and cache it in memory.
  */
-async function readStaticImage(url: string) {
-    logOnCloudflareOnly(`Reading static image: ${url}, cache size: ${staticCache.size}`);
-    return getWithCache(`static-image:${url}`, () => readSelfImage(url));
+async function fetchStaticImage(url: string) {
+    return getWithCache(`static-image:${url}`, () => fetchImage(url));
 }
 
 /**
- * Read an image from GitBook itself.
+ * Fetch an image from a URL and return a base64 encoded string.
+ * We do this as @vercel/og is otherwise failing on SVG images referenced by a URL.
  */
-async function readSelfImage(url: string) {
+async function fetchImage(url: string) {
     const response = await fetch(url);
-    const image = await readImage(response);
-    return image;
+
+    const contentType = response.headers.get('content-type');
+    if (!contentType || !contentType.startsWith('image/')) {
+        throw new Error(`Invalid content type: ${contentType}`);
+    }
+
+    const arrayBuffer = await response.arrayBuffer();
+    const buffer = Buffer.from(arrayBuffer);
+    const base64 = buffer.toString('base64');
+    const src = `data:${contentType};base64,${base64}`;
+
+    try {
+        const { width, height } = imageSize(buffer);
+        return { src, width, height };
+    } catch (error) {
+        console.error(`Error reading image size: ${error}`);
+        return { src };
+    }
 }

From af98402655945a47473828cce1b8b33e4b858683 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Samy=20Pess=C3=A9?= <samypesse@gmail.com>
Date: Mon, 16 Jun 2025 19:15:22 +0200
Subject: [PATCH 11/23] Add support for inline icons (#3329)

---
 .changeset/curly-rules-learn.md               |  5 +++
 bun.lock                                      |  4 +--
 package.json                                  |  2 +-
 packages/gitbook/e2e/internal.spec.ts         |  5 +++
 .../DocumentView/CodeBlock/highlight.ts       | 31 +++++++++++++------
 .../src/components/DocumentView/Inline.tsx    |  3 ++
 .../components/DocumentView/InlineIcon.tsx    | 10 ++++++
 7 files changed, 48 insertions(+), 12 deletions(-)
 create mode 100644 .changeset/curly-rules-learn.md
 create mode 100644 packages/gitbook/src/components/DocumentView/InlineIcon.tsx

diff --git a/.changeset/curly-rules-learn.md b/.changeset/curly-rules-learn.md
new file mode 100644
index 000000000..47400e919
--- /dev/null
+++ b/.changeset/curly-rules-learn.md
@@ -0,0 +1,5 @@
+---
+"gitbook": minor
+---
+
+Add support for inline icons.
diff --git a/bun.lock b/bun.lock
index 1c192ca71..94b4fc3a5 100644
--- a/bun.lock
+++ b/bun.lock
@@ -285,7 +285,7 @@
     "react-dom": "^19.0.0",
   },
   "catalog": {
-    "@gitbook/api": "^0.120.0",
+    "@gitbook/api": "^0.121.0",
   },
   "packages": {
     "@ai-sdk/provider": ["@ai-sdk/provider@1.1.0", "", { "dependencies": { "json-schema": "^0.4.0" } }, "sha512-0M+qjp+clUD0R1E5eWQFhxEvWLNaOtGQRUaBn8CUABnSKredagq92hUS9VjOzGsTm37xLfpaxl97AVtbeOsHew=="],
@@ -650,7 +650,7 @@
 
     "@fortawesome/fontawesome-svg-core": ["@fortawesome/fontawesome-svg-core@6.6.0", "", { "dependencies": { "@fortawesome/fontawesome-common-types": "6.6.0" } }, "sha512-KHwPkCk6oRT4HADE7smhfsKudt9N/9lm6EJ5BVg0tD1yPA5hht837fB87F8pn15D8JfTqQOjhKTktwmLMiD7Kg=="],
 
-    "@gitbook/api": ["@gitbook/api@0.120.0", "", { "dependencies": { "event-iterator": "^2.0.0", "eventsource-parser": "^3.0.0" } }, "sha512-FiRmPiSBwobMxmNjd14QkkOdM95BAPLDDRShgpS9Vsd8lHjNMyZfrJKVJTsJUuFcgYoi4cqNw9yu/TiUBUgv3g=="],
+    "@gitbook/api": ["@gitbook/api@0.121.0", "", { "dependencies": { "event-iterator": "^2.0.0", "eventsource-parser": "^3.0.0" } }, "sha512-o4/N24RM0Rg8S/3yPDjPmt6TbQF+1iZmg9q9QKxOxMqpQ2bZmMUqS7dSkeqEbEBMALx/m/x0xQlJbEJGbOwteg=="],
 
     "@gitbook/cache-do": ["@gitbook/cache-do@workspace:packages/cache-do"],
 
diff --git a/package.json b/package.json
index 1faa750ba..1cf5326c1 100644
--- a/package.json
+++ b/package.json
@@ -36,7 +36,7 @@
     "workspaces": {
         "packages": ["packages/*"],
         "catalog": {
-            "@gitbook/api": "^0.120.0"
+            "@gitbook/api": "^0.121.0"
         }
     },
     "patchedDependencies": {
diff --git a/packages/gitbook/e2e/internal.spec.ts b/packages/gitbook/e2e/internal.spec.ts
index 3efe00bd2..3a884ae5e 100644
--- a/packages/gitbook/e2e/internal.spec.ts
+++ b/packages/gitbook/e2e/internal.spec.ts
@@ -603,6 +603,11 @@ const testCases: TestsCase[] = [
                 url: 'blocks/emojis',
                 run: waitForCookiesDialog,
             },
+            {
+                name: 'Icons',
+                url: 'blocks/icons',
+                run: waitForCookiesDialog,
+            },
             {
                 name: 'Links',
                 url: 'blocks/links',
diff --git a/packages/gitbook/src/components/DocumentView/CodeBlock/highlight.ts b/packages/gitbook/src/components/DocumentView/CodeBlock/highlight.ts
index eb02b5b92..89d00dafb 100644
--- a/packages/gitbook/src/components/DocumentView/CodeBlock/highlight.ts
+++ b/packages/gitbook/src/components/DocumentView/CodeBlock/highlight.ts
@@ -12,6 +12,7 @@ import {
 import { createJavaScriptRegexEngine } from 'shiki/engine/javascript';
 import { type BundledLanguage, bundledLanguages } from 'shiki/langs';
 
+import { nullIfNever } from '@/lib/typescript';
 import { plainHighlight } from './plain-highlight';
 
 export type HighlightLine = {
@@ -263,16 +264,28 @@ function getPlainCodeBlockLine(
         if (node.object === 'text') {
             content += cleanupLine(node.leaves.map((leaf) => leaf.text).join(''));
         } else {
-            const start = index + content.length;
-            content += getPlainCodeBlockLine(node, index + content.length, inlines);
-            const end = index + content.length;
+            switch (node.type) {
+                case 'annotation': {
+                    const start = index + content.length;
+                    content += getPlainCodeBlockLine(node, index + content.length, inlines);
+                    const end = index + content.length;
 
-            if (inlines) {
-                inlines.push({
-                    inline: node,
-                    start,
-                    end,
-                });
+                    if (inlines) {
+                        inlines.push({
+                            inline: node,
+                            start,
+                            end,
+                        });
+                    }
+                    break;
+                }
+                case 'expression': {
+                    break;
+                }
+                default: {
+                    nullIfNever(node);
+                    break;
+                }
             }
         }
     }
diff --git a/packages/gitbook/src/components/DocumentView/Inline.tsx b/packages/gitbook/src/components/DocumentView/Inline.tsx
index 1e1b091ce..84b56decf 100644
--- a/packages/gitbook/src/components/DocumentView/Inline.tsx
+++ b/packages/gitbook/src/components/DocumentView/Inline.tsx
@@ -5,6 +5,7 @@ import { Annotation } from './Annotation/Annotation';
 import type { DocumentContextProps } from './DocumentView';
 import { Emoji } from './Emoji';
 import { InlineButton } from './InlineButton';
+import { InlineIcon } from './InlineIcon';
 import { InlineImage } from './InlineImage';
 import { InlineLink } from './InlineLink';
 import { InlineMath } from './Math';
@@ -47,6 +48,8 @@ export function Inline<T extends DocumentInline>(props: InlineProps<T>) {
             return <InlineImage {...contextProps} inline={inline} />;
         case 'button':
             return <InlineButton {...contextProps} inline={inline} />;
+        case 'icon':
+            return <InlineIcon {...contextProps} inline={inline} />;
         case 'expression':
             // The GitBook API should take care of evaluating expressions.
             // We should never need to render them.
diff --git a/packages/gitbook/src/components/DocumentView/InlineIcon.tsx b/packages/gitbook/src/components/DocumentView/InlineIcon.tsx
new file mode 100644
index 000000000..0eca373f6
--- /dev/null
+++ b/packages/gitbook/src/components/DocumentView/InlineIcon.tsx
@@ -0,0 +1,10 @@
+import type { DocumentInlineIcon } from '@gitbook/api';
+
+import { Icon, type IconName } from '@gitbook/icons';
+import type { InlineProps } from './Inline';
+
+export async function InlineIcon(props: InlineProps<DocumentInlineIcon>) {
+    const { inline } = props;
+
+    return <Icon icon={inline.data.icon as IconName} className="inline size-[1em]" />;
+}

From 11a6511b7aa7d1052c887417d97d4eede6104daa Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Samy=20Pess=C3=A9?= <samypesse@gmail.com>
Date: Mon, 16 Jun 2025 20:06:33 +0200
Subject: [PATCH 12/23] Fix crash when integration script fails to render block
 (#3332)

---
 .changeset/famous-melons-compete.md           |  5 +++
 .changeset/orange-ears-drop.md                |  5 +++
 packages/gitbook-v2/src/lib/data/errors.ts    | 34 ++++++++++++---
 .../Integration/IntegrationBlock.tsx          | 34 +++++++++------
 .../DocumentView/Integration/render.ts        | 31 ++++++++++++++
 .../Integration/server-actions.tsx            | 21 ++++++----
 packages/react-contentkit/src/ContentKit.tsx  | 41 ++++++++++++-------
 7 files changed, 129 insertions(+), 42 deletions(-)
 create mode 100644 .changeset/famous-melons-compete.md
 create mode 100644 .changeset/orange-ears-drop.md
 create mode 100644 packages/gitbook/src/components/DocumentView/Integration/render.ts

diff --git a/.changeset/famous-melons-compete.md b/.changeset/famous-melons-compete.md
new file mode 100644
index 000000000..17512b6f4
--- /dev/null
+++ b/.changeset/famous-melons-compete.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix crash when integration script fails to render block.
diff --git a/.changeset/orange-ears-drop.md b/.changeset/orange-ears-drop.md
new file mode 100644
index 000000000..12dd7fae5
--- /dev/null
+++ b/.changeset/orange-ears-drop.md
@@ -0,0 +1,5 @@
+---
+"@gitbook/react-contentkit": patch
+---
+
+Add basic error handling when transitioning between states.
diff --git a/packages/gitbook-v2/src/lib/data/errors.ts b/packages/gitbook-v2/src/lib/data/errors.ts
index 784eebdbb..4059fb5c9 100644
--- a/packages/gitbook-v2/src/lib/data/errors.ts
+++ b/packages/gitbook-v2/src/lib/data/errors.ts
@@ -47,11 +47,7 @@ export function getDataOrNull<T>(
         return response.then((result) => getDataOrNull(result, ignoreErrors));
     }
 
-    if (response.error) {
-        if (ignoreErrors.includes(response.error.code)) return null;
-        throw new DataFetcherError(response.error.message, response.error.code);
-    }
-    return response.data;
+    return ignoreDataFetcherErrors(response, ignoreErrors).data ?? null;
 }
 
 /**
@@ -93,6 +89,34 @@ export async function wrapDataFetcherError<T>(
     }
 }
 
+/**
+ * Ignore some data fetcher errors.
+ */
+export function ignoreDataFetcherErrors<T>(
+    response: DataFetcherResponse<T>,
+    ignoreErrors?: number[]
+): DataFetcherResponse<T>;
+export function ignoreDataFetcherErrors<T>(
+    response: Promise<DataFetcherResponse<T>>,
+    ignoreErrors?: number[]
+): Promise<DataFetcherResponse<T>>;
+export function ignoreDataFetcherErrors<T>(
+    response: DataFetcherResponse<T> | Promise<DataFetcherResponse<T>>,
+    ignoreErrors: number[] = [404]
+): DataFetcherResponse<T> | Promise<DataFetcherResponse<T>> {
+    if (response instanceof Promise) {
+        return response.then((result) => ignoreDataFetcherErrors(result, ignoreErrors));
+    }
+
+    if (response.error) {
+        if (ignoreErrors.includes(response.error.code)) {
+            return response;
+        }
+        throw new DataFetcherError(response.error.message, response.error.code);
+    }
+    return response;
+}
+
 /**
  * Get a data fetcher exposable error from a JS error.
  */
diff --git a/packages/gitbook/src/components/DocumentView/Integration/IntegrationBlock.tsx b/packages/gitbook/src/components/DocumentView/Integration/IntegrationBlock.tsx
index 6ebec6f03..a26aa3bfd 100644
--- a/packages/gitbook/src/components/DocumentView/Integration/IntegrationBlock.tsx
+++ b/packages/gitbook/src/components/DocumentView/Integration/IntegrationBlock.tsx
@@ -5,8 +5,8 @@ import { GITBOOK_INTEGRATIONS_HOST } from '@v2/lib/env';
 
 import type { BlockProps } from '../Block';
 import './contentkit.css';
-import { getDataOrNull } from '@v2/lib/data';
 import { contentKitServerContext } from './contentkit';
+import { fetchSafeIntegrationUI } from './render';
 import { renderIntegrationUi } from './server-actions';
 
 export async function IntegrationBlock(props: BlockProps<DocumentBlockIntegration>) {
@@ -16,8 +16,6 @@ export async function IntegrationBlock(props: BlockProps<DocumentBlockIntegratio
         throw new Error('integration block requires a content.spaceId');
     }
 
-    const { dataFetcher } = context.contentContext;
-
     const initialInput: RenderIntegrationUI = {
         componentId: block.data.block,
         props: block.data.props,
@@ -30,17 +28,27 @@ export async function IntegrationBlock(props: BlockProps<DocumentBlockIntegratio
         },
     };
 
-    const initialOutput = await getDataOrNull(
-        dataFetcher.renderIntegrationUi({
-            integrationName: block.data.integration,
-            request: initialInput,
-        }),
+    const initialResponse = await fetchSafeIntegrationUI(context.contentContext, {
+        integrationName: block.data.integration,
+        request: initialInput,
+    });
 
-        // The API can respond with a 400 error if the integration is not installed
-        // and 404 if the integration is not found.
-        [404, 400]
-    );
-    if (!initialOutput || initialOutput.type === 'complete') {
+    if (initialResponse.error) {
+        if (initialResponse.error.code === 404) {
+            return null;
+        }
+
+        return (
+            <div className={tcls(style)}>
+                <pre>
+                    Unexpected error with integration {block.data.integration}:{' '}
+                    {initialResponse.error.message}
+                </pre>
+            </div>
+        );
+    }
+    const initialOutput = initialResponse.data;
+    if (initialOutput.type === 'complete') {
         return null;
     }
 
diff --git a/packages/gitbook/src/components/DocumentView/Integration/render.ts b/packages/gitbook/src/components/DocumentView/Integration/render.ts
new file mode 100644
index 000000000..a9a86c9e5
--- /dev/null
+++ b/packages/gitbook/src/components/DocumentView/Integration/render.ts
@@ -0,0 +1,31 @@
+import type { RenderIntegrationUI } from '@gitbook/api';
+import type { GitBookBaseContext } from '@v2/lib/context';
+import { ignoreDataFetcherErrors } from '@v2/lib/data';
+
+/**
+ * Render an integration UI while ignoring some errors.
+ */
+export async function fetchSafeIntegrationUI(
+    context: GitBookBaseContext,
+    {
+        integrationName,
+        request,
+    }: {
+        integrationName: string;
+        request: RenderIntegrationUI;
+    }
+) {
+    const output = await ignoreDataFetcherErrors(
+        context.dataFetcher.renderIntegrationUi({
+            integrationName,
+            request,
+        }),
+
+        // The API can respond with a 400 error if the integration is not installed
+        // and 404 if the integration is not found.
+        // The API can also respond with a 502 error if the integration is not generating a proper response.
+        [404, 400, 502]
+    );
+
+    return output;
+}
diff --git a/packages/gitbook/src/components/DocumentView/Integration/server-actions.tsx b/packages/gitbook/src/components/DocumentView/Integration/server-actions.tsx
index 54180e5c8..91d1e0e73 100644
--- a/packages/gitbook/src/components/DocumentView/Integration/server-actions.tsx
+++ b/packages/gitbook/src/components/DocumentView/Integration/server-actions.tsx
@@ -4,9 +4,9 @@ import { getV1BaseContext } from '@/lib/v1';
 import { isV2 } from '@/lib/v2';
 import type { RenderIntegrationUI } from '@gitbook/api';
 import { ContentKitOutput } from '@gitbook/react-contentkit';
-import { throwIfDataError } from '@v2/lib/data';
 import { getServerActionBaseContext } from '@v2/lib/server-actions';
 import { contentKitServerContext } from './contentkit';
+import { fetchSafeIntegrationUI } from './render';
 
 /**
  * Server action to render an integration UI request from <ContentKit />.
@@ -22,16 +22,19 @@ export async function renderIntegrationUi({
     request: RenderIntegrationUI;
 }) {
     const serverAction = isV2() ? await getServerActionBaseContext() : await getV1BaseContext();
+    const output = await fetchSafeIntegrationUI(serverAction, {
+        integrationName: renderContext.integrationName,
+        request,
+    });
 
-    const output = await throwIfDataError(
-        serverAction.dataFetcher.renderIntegrationUi({
-            integrationName: renderContext.integrationName,
-            request,
-        })
-    );
+    if (output.error) {
+        return {
+            error: output.error.message,
+        };
+    }
 
     return {
-        children: <ContentKitOutput output={output} context={contentKitServerContext} />,
-        output: output,
+        children: <ContentKitOutput output={output.data} context={contentKitServerContext} />,
+        output: output.data,
     };
 }
diff --git a/packages/react-contentkit/src/ContentKit.tsx b/packages/react-contentkit/src/ContentKit.tsx
index 9d53c70de..4f413f367 100644
--- a/packages/react-contentkit/src/ContentKit.tsx
+++ b/packages/react-contentkit/src/ContentKit.tsx
@@ -38,10 +38,18 @@ export function ContentKit<RenderContext>(props: {
     render: (input: {
         renderContext: RenderContext;
         request: RequestRenderIntegrationUI;
-    }) => Promise<{
-        children: React.ReactNode;
-        output: ContentKitRenderOutput;
-    }>;
+    }) => Promise<
+        | {
+              error?: undefined;
+              children: React.ReactNode;
+              output: ContentKitRenderOutput;
+          }
+        | {
+              error: string;
+              children?: undefined;
+              output?: undefined;
+          }
+    >;
     /** Callback when an action is triggered */
     onAction?: (action: ContentKitAction) => void;
     /** Callback when the flow is completed */
@@ -98,17 +106,18 @@ export function ContentKit<RenderContext>(props: {
                 request: newInput,
             });
             const output = result.output;
+            if (output) {
+                if (output.type === 'complete') {
+                    return onComplete?.(output.returnValue);
+                }
 
-            if (output.type === 'complete') {
-                return onComplete?.(output.returnValue);
+                setCurrent((prev) => ({
+                    input: newInput,
+                    children: result.children,
+                    output: output,
+                    state: prev.state,
+                }));
             }
-
-            setCurrent((prev) => ({
-                input: newInput,
-                children: result.children,
-                output: output,
-                state: prev.state,
-            }));
         },
         [setCurrent, current, render, onComplete]
     );
@@ -147,8 +156,10 @@ export function ContentKit<RenderContext>(props: {
                             renderContext,
                             request: modalInput,
                         });
-
-                        if (result.output.type === 'element' || !result.output.type) {
+                        if (
+                            result.output &&
+                            (result.output.type === 'element' || !result.output.type)
+                        ) {
                             setSubView({
                                 mode: 'modal',
                                 initialInput: modalInput,

From dfa8a37be19c1868bb1c833631f199b4f52b3305 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Samy=20Pess=C3=A9?= <samypesse@gmail.com>
Date: Tue, 17 Jun 2025 00:16:52 +0200
Subject: [PATCH 13/23] Don't cache unexpected API errors for more than a few
 minutes (#3334)

---
 .changeset/real-walls-glow.md              |   5 +
 packages/gitbook-v2/src/lib/data/api.ts    | 203 +++++++++++----------
 packages/gitbook-v2/src/lib/data/errors.ts |  17 ++
 3 files changed, 125 insertions(+), 100 deletions(-)
 create mode 100644 .changeset/real-walls-glow.md

diff --git a/.changeset/real-walls-glow.md b/.changeset/real-walls-glow.md
new file mode 100644
index 000000000..277c39ca9
--- /dev/null
+++ b/.changeset/real-walls-glow.md
@@ -0,0 +1,5 @@
+---
+"gitbook-v2": patch
+---
+
+Don't cache unexpected API errors for more than a few minutes.
diff --git a/packages/gitbook-v2/src/lib/data/api.ts b/packages/gitbook-v2/src/lib/data/api.ts
index d36c2445f..8e6535331 100644
--- a/packages/gitbook-v2/src/lib/data/api.ts
+++ b/packages/gitbook-v2/src/lib/data/api.ts
@@ -9,7 +9,7 @@ import { getCacheTag, getComputedContentSourceCacheTags } from '@gitbook/cache-t
 import { GITBOOK_API_TOKEN, GITBOOK_API_URL, GITBOOK_USER_AGENT } from '@v2/lib/env';
 import { unstable_cacheLife as cacheLife, unstable_cacheTag as cacheTag } from 'next/cache';
 import { cache } from '../cache';
-import { DataFetcherError, wrapDataFetcherError } from './errors';
+import { DataFetcherError, wrapCacheDataFetcherError } from './errors';
 import type { GitBookDataFetcher } from './types';
 
 interface DataFetcherInput {
@@ -206,8 +206,8 @@ export function createDataFetcher(
 
 const getUserById = cache(async (input: DataFetcherInput, params: { userId: string }) => {
     'use cache';
-    return trace(`getUserById(${params.userId})`, async () => {
-        return wrapDataFetcherError(async () => {
+    return wrapCacheDataFetcherError(async () => {
+        return trace(`getUserById(${params.userId})`, async () => {
             const api = apiClient(input);
             const res = await api.users.getUserById(params.userId, {
                 ...noCacheFetchOptions,
@@ -229,8 +229,8 @@ const getSpace = cache(
             })
         );
 
-        return trace(`getSpace(${params.spaceId}, ${params.shareKey})`, async () => {
-            return wrapDataFetcherError(async () => {
+        return wrapCacheDataFetcherError(async () => {
+            return trace(`getSpace(${params.spaceId}, ${params.shareKey})`, async () => {
                 const api = apiClient(input);
                 const res = await api.spaces.getSpaceById(
                     params.spaceId,
@@ -260,20 +260,23 @@ const getChangeRequest = cache(
             })
         );
 
-        return trace(`getChangeRequest(${params.spaceId}, ${params.changeRequestId})`, async () => {
-            return wrapDataFetcherError(async () => {
-                const api = apiClient(input);
-                const res = await api.spaces.getChangeRequestById(
-                    params.spaceId,
-                    params.changeRequestId,
-                    {
-                        ...noCacheFetchOptions,
-                    }
-                );
-                cacheTag(...getCacheTagsFromResponse(res));
-                cacheLife('minutes');
-                return res.data;
-            });
+        return wrapCacheDataFetcherError(async () => {
+            return trace(
+                `getChangeRequest(${params.spaceId}, ${params.changeRequestId})`,
+                async () => {
+                    const api = apiClient(input);
+                    const res = await api.spaces.getChangeRequestById(
+                        params.spaceId,
+                        params.changeRequestId,
+                        {
+                            ...noCacheFetchOptions,
+                        }
+                    );
+                    cacheTag(...getCacheTagsFromResponse(res));
+                    cacheLife('minutes');
+                    return res.data;
+                }
+            );
         });
     }
 );
@@ -284,8 +287,8 @@ const getRevision = cache(
         params: { spaceId: string; revisionId: string; metadata: boolean }
     ) => {
         'use cache';
-        return trace(`getRevision(${params.spaceId}, ${params.revisionId})`, async () => {
-            return wrapDataFetcherError(async () => {
+        return wrapCacheDataFetcherError(async () => {
+            return trace(`getRevision(${params.spaceId}, ${params.revisionId})`, async () => {
                 const api = apiClient(input);
                 const res = await api.spaces.getRevisionById(
                     params.spaceId,
@@ -311,8 +314,8 @@ const getRevisionPages = cache(
         params: { spaceId: string; revisionId: string; metadata: boolean }
     ) => {
         'use cache';
-        return trace(`getRevisionPages(${params.spaceId}, ${params.revisionId})`, async () => {
-            return wrapDataFetcherError(async () => {
+        return wrapCacheDataFetcherError(async () => {
+            return trace(`getRevisionPages(${params.spaceId}, ${params.revisionId})`, async () => {
                 const api = apiClient(input);
                 const res = await api.spaces.listPagesInRevisionById(
                     params.spaceId,
@@ -338,10 +341,10 @@ const getRevisionFile = cache(
         params: { spaceId: string; revisionId: string; fileId: string }
     ) => {
         'use cache';
-        return trace(
-            `getRevisionFile(${params.spaceId}, ${params.revisionId}, ${params.fileId})`,
-            async () => {
-                return wrapDataFetcherError(async () => {
+        return wrapCacheDataFetcherError(async () => {
+            return trace(
+                `getRevisionFile(${params.spaceId}, ${params.revisionId}, ${params.fileId})`,
+                async () => {
                     const api = apiClient(input);
                     const res = await api.spaces.getFileInRevisionById(
                         params.spaceId,
@@ -355,9 +358,9 @@ const getRevisionFile = cache(
                     cacheTag(...getCacheTagsFromResponse(res));
                     cacheLife('max');
                     return res.data;
-                });
-            }
-        );
+                }
+            );
+        });
     }
 );
 
@@ -367,10 +370,10 @@ const getRevisionPageMarkdown = cache(
         params: { spaceId: string; revisionId: string; pageId: string }
     ) => {
         'use cache';
-        return trace(
-            `getRevisionPageMarkdown(${params.spaceId}, ${params.revisionId}, ${params.pageId})`,
-            async () => {
-                return wrapDataFetcherError(async () => {
+        return wrapCacheDataFetcherError(async () => {
+            return trace(
+                `getRevisionPageMarkdown(${params.spaceId}, ${params.revisionId}, ${params.pageId})`,
+                async () => {
                     const api = apiClient(input);
                     const res = await api.spaces.getPageInRevisionById(
                         params.spaceId,
@@ -391,9 +394,9 @@ const getRevisionPageMarkdown = cache(
                         throw new DataFetcherError('Page is not a document', 404);
                     }
                     return res.data.markdown;
-                });
-            }
-        );
+                }
+            );
+        });
     }
 );
 
@@ -403,10 +406,10 @@ const getRevisionPageDocument = cache(
         params: { spaceId: string; revisionId: string; pageId: string }
     ) => {
         'use cache';
-        return trace(
-            `getRevisionPageDocument(${params.spaceId}, ${params.revisionId}, ${params.pageId})`,
-            async () => {
-                return wrapDataFetcherError(async () => {
+        return wrapCacheDataFetcherError(async () => {
+            return trace(
+                `getRevisionPageDocument(${params.spaceId}, ${params.revisionId}, ${params.pageId})`,
+                async () => {
                     const api = apiClient(input);
                     const res = await api.spaces.getPageDocumentInRevisionById(
                         params.spaceId,
@@ -424,9 +427,9 @@ const getRevisionPageDocument = cache(
                     cacheLife('max');
 
                     return res.data;
-                });
-            }
-        );
+                }
+            );
+        });
     }
 );
 
@@ -436,11 +439,11 @@ const getRevisionPageByPath = cache(
         params: { spaceId: string; revisionId: string; path: string }
     ) => {
         'use cache';
-        return trace(
-            `getRevisionPageByPath(${params.spaceId}, ${params.revisionId}, ${params.path})`,
-            async () => {
-                const encodedPath = encodeURIComponent(params.path);
-                return wrapDataFetcherError(async () => {
+        return wrapCacheDataFetcherError(async () => {
+            return trace(
+                `getRevisionPageByPath(${params.spaceId}, ${params.revisionId}, ${params.path})`,
+                async () => {
+                    const encodedPath = encodeURIComponent(params.path);
                     const api = apiClient(input);
                     const res = await api.spaces.getPageInRevisionByPath(
                         params.spaceId,
@@ -454,17 +457,17 @@ const getRevisionPageByPath = cache(
                     cacheTag(...getCacheTagsFromResponse(res));
                     cacheLife('max');
                     return res.data;
-                });
-            }
-        );
+                }
+            );
+        });
     }
 );
 
 const getDocument = cache(
     async (input: DataFetcherInput, params: { spaceId: string; documentId: string }) => {
         'use cache';
-        return trace(`getDocument(${params.spaceId}, ${params.documentId})`, async () => {
-            return wrapDataFetcherError(async () => {
+        return wrapCacheDataFetcherError(async () => {
+            return trace(`getDocument(${params.spaceId}, ${params.documentId})`, async () => {
                 const api = apiClient(input);
                 const res = await api.spaces.getDocumentById(
                     params.spaceId,
@@ -503,10 +506,10 @@ const getComputedDocument = cache(
             )
         );
 
-        return trace(
-            `getComputedDocument(${params.spaceId}, ${params.organizationId}, ${params.source.type}, ${params.seed})`,
-            async () => {
-                return wrapDataFetcherError(async () => {
+        return wrapCacheDataFetcherError(async () => {
+            return trace(
+                `getComputedDocument(${params.spaceId}, ${params.organizationId}, ${params.source.type}, ${params.seed})`,
+                async () => {
                     const api = apiClient(input);
                     const res = await api.spaces.getComputedDocument(
                         params.spaceId,
@@ -522,9 +525,9 @@ const getComputedDocument = cache(
                     cacheTag(...getCacheTagsFromResponse(res));
                     cacheLife('max');
                     return res.data;
-                });
-            }
-        );
+                }
+            );
+        });
     }
 );
 
@@ -534,10 +537,10 @@ const getReusableContent = cache(
         params: { spaceId: string; revisionId: string; reusableContentId: string }
     ) => {
         'use cache';
-        return trace(
-            `getReusableContent(${params.spaceId}, ${params.revisionId}, ${params.reusableContentId})`,
-            async () => {
-                return wrapDataFetcherError(async () => {
+        return wrapCacheDataFetcherError(async () => {
+            return trace(
+                `getReusableContent(${params.spaceId}, ${params.revisionId}, ${params.reusableContentId})`,
+                async () => {
                     const api = apiClient(input);
                     const res = await api.spaces.getReusableContentInRevisionById(
                         params.spaceId,
@@ -551,9 +554,9 @@ const getReusableContent = cache(
                     cacheTag(...getCacheTagsFromResponse(res));
                     cacheLife('max');
                     return res.data;
-                });
-            }
-        );
+                }
+            );
+        });
     }
 );
 
@@ -568,10 +571,10 @@ const getLatestOpenAPISpecVersionContent = cache(
             })
         );
 
-        return trace(
-            `getLatestOpenAPISpecVersionContent(${params.organizationId}, ${params.slug})`,
-            async () => {
-                return wrapDataFetcherError(async () => {
+        return wrapCacheDataFetcherError(async () => {
+            return trace(
+                `getLatestOpenAPISpecVersionContent(${params.organizationId}, ${params.slug})`,
+                async () => {
                     const api = apiClient(input);
                     const res = await api.orgs.getLatestOpenApiSpecVersionContent(
                         params.organizationId,
@@ -583,9 +586,9 @@ const getLatestOpenAPISpecVersionContent = cache(
                     cacheTag(...getCacheTagsFromResponse(res));
                     cacheLife('max');
                     return res.data;
-                });
-            }
-        );
+                }
+            );
+        });
     }
 );
 
@@ -602,10 +605,10 @@ const getPublishedContentSite = cache(
             })
         );
 
-        return trace(
-            `getPublishedContentSite(${params.organizationId}, ${params.siteId}, ${params.siteShareKey})`,
-            async () => {
-                return wrapDataFetcherError(async () => {
+        return wrapCacheDataFetcherError(async () => {
+            return trace(
+                `getPublishedContentSite(${params.organizationId}, ${params.siteId}, ${params.siteShareKey})`,
+                async () => {
                     const api = apiClient(input);
                     const res = await api.orgs.getPublishedContentSite(
                         params.organizationId,
@@ -620,9 +623,9 @@ const getPublishedContentSite = cache(
                     cacheTag(...getCacheTagsFromResponse(res));
                     cacheLife('days');
                     return res.data;
-                });
-            }
-        );
+                }
+            );
+        });
     }
 );
 
@@ -644,10 +647,10 @@ const getSiteRedirectBySource = cache(
             })
         );
 
-        return trace(
-            `getSiteRedirectBySource(${params.organizationId}, ${params.siteId}, ${params.siteShareKey}, ${params.source})`,
-            async () => {
-                return wrapDataFetcherError(async () => {
+        return wrapCacheDataFetcherError(async () => {
+            return trace(
+                `getSiteRedirectBySource(${params.organizationId}, ${params.siteId}, ${params.siteShareKey}, ${params.source})`,
+                async () => {
                     const api = apiClient(input);
                     const res = await api.orgs.getSiteRedirectBySource(
                         params.organizationId,
@@ -663,9 +666,9 @@ const getSiteRedirectBySource = cache(
                     cacheTag(...getCacheTagsFromResponse(res));
                     cacheLife('days');
                     return res.data;
-                });
-            }
-        );
+                }
+            );
+        });
     }
 );
 
@@ -679,8 +682,8 @@ const getEmbedByUrl = cache(
             })
         );
 
-        return trace(`getEmbedByUrl(${params.spaceId}, ${params.url})`, async () => {
-            return wrapDataFetcherError(async () => {
+        return wrapCacheDataFetcherError(async () => {
+            return trace(`getEmbedByUrl(${params.spaceId}, ${params.url})`, async () => {
                 const api = apiClient(input);
                 const res = await api.spaces.getEmbedByUrlInSpace(
                     params.spaceId,
@@ -712,10 +715,10 @@ const searchSiteContent = cache(
             })
         );
 
-        return trace(
-            `searchSiteContent(${params.organizationId}, ${params.siteId}, ${params.query})`,
-            async () => {
-                return wrapDataFetcherError(async () => {
+        return wrapCacheDataFetcherError(async () => {
+            return trace(
+                `searchSiteContent(${params.organizationId}, ${params.siteId}, ${params.query})`,
+                async () => {
                     const { organizationId, siteId, query, scope } = params;
                     const api = apiClient(input);
                     const res = await api.orgs.searchSiteContent(
@@ -733,9 +736,9 @@ const searchSiteContent = cache(
                     cacheTag(...getCacheTagsFromResponse(res));
                     cacheLife('hours');
                     return res.data.items;
-                });
-            }
-        );
+                }
+            );
+        });
     }
 );
 
@@ -752,8 +755,8 @@ const renderIntegrationUi = cache(
             })
         );
 
-        return trace(`renderIntegrationUi(${params.integrationName})`, async () => {
-            return wrapDataFetcherError(async () => {
+        return wrapCacheDataFetcherError(async () => {
+            return trace(`renderIntegrationUi(${params.integrationName})`, async () => {
                 const api = apiClient(input);
                 const res = await api.integrations.renderIntegrationUiWithPost(
                     params.integrationName,
diff --git a/packages/gitbook-v2/src/lib/data/errors.ts b/packages/gitbook-v2/src/lib/data/errors.ts
index 4059fb5c9..c4d983ec2 100644
--- a/packages/gitbook-v2/src/lib/data/errors.ts
+++ b/packages/gitbook-v2/src/lib/data/errors.ts
@@ -1,4 +1,5 @@
 import { GitBookAPIError } from '@gitbook/api';
+import { unstable_cacheLife as cacheLife } from 'next/cache';
 import type { DataFetcherErrorData, DataFetcherResponse } from './types';
 
 export class DataFetcherError extends Error {
@@ -89,6 +90,22 @@ export async function wrapDataFetcherError<T>(
     }
 }
 
+/**
+ * Wrap an async execution to handle errors and return a DataFetcherResponse.
+ * This should be used inside 'use cache' functions.
+ */
+export async function wrapCacheDataFetcherError<T>(
+    fn: () => Promise<T>
+): Promise<DataFetcherResponse<T>> {
+    const result = await wrapDataFetcherError(fn);
+    if (result.error && result.error.code >= 500) {
+        // We don't want to cache errors for too long.
+        // as the API might
+        cacheLife('minutes');
+    }
+    return result;
+}
+
 /**
  * Ignore some data fetcher errors.
  */

From 6859f7d2391482323667c170b5fb144d1b2fd49f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Samy=20Pess=C3=A9?= <samypesse@gmail.com>
Date: Tue, 17 Jun 2025 00:31:07 +0200
Subject: [PATCH 14/23] Fix rendering of ogimage when logo or icon are AVIF
 images (#3336)

Co-authored-by: Steven H <steven@gitbook.io>
---
 .changeset/pretty-balloons-fold.md      |  5 ++
 packages/gitbook/src/routes/ogimage.tsx | 80 ++++++++++++++++++-------
 2 files changed, 64 insertions(+), 21 deletions(-)
 create mode 100644 .changeset/pretty-balloons-fold.md

diff --git a/.changeset/pretty-balloons-fold.md b/.changeset/pretty-balloons-fold.md
new file mode 100644
index 000000000..b50187984
--- /dev/null
+++ b/.changeset/pretty-balloons-fold.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix rendering of ogimage when logo or icon are AVIF images.
diff --git a/packages/gitbook/src/routes/ogimage.tsx b/packages/gitbook/src/routes/ogimage.tsx
index 653fc8fc3..4035f54be 100644
--- a/packages/gitbook/src/routes/ogimage.tsx
+++ b/packages/gitbook/src/routes/ogimage.tsx
@@ -8,6 +8,7 @@ import { ImageResponse } from 'next/og';
 import { type PageParams, fetchPageData } from '@/components/SitePage';
 import { getFontSourcesToPreload } from '@/fonts/custom';
 import { getAssetURL } from '@/lib/assets';
+import { getExtension } from '@/lib/paths';
 import { filterOutNullable } from '@/lib/typescript';
 import { getCacheTag } from '@gitbook/cache-tags';
 import type { GitBookSiteContext } from '@v2/lib/context';
@@ -32,7 +33,6 @@ export async function serveOGImage(baseContext: GitBookSiteContext, params: Page
     }
 
     // Compute all text to load only the necessary fonts
-    const contentTitle = customization.header.logo ? '' : site.title;
     const pageTitle = page
         ? page.title.length > 64
             ? `${page.title.slice(0, 64)}...`
@@ -52,7 +52,7 @@ export async function serveOGImage(baseContext: GitBookSiteContext, params: Page
             const fontFamily = customization.styling.font ?? CustomizationDefaultFont.Inter;
 
             const regularText = pageDescription;
-            const boldText = `${contentTitle}${pageTitle}`;
+            const boldText = `${site.title} ${pageTitle}`;
 
             const fonts = (
                 await Promise.all([
@@ -164,10 +164,28 @@ export async function serveOGImage(baseContext: GitBookSiteContext, params: Page
                 )
             )
         );
+        if (!iconImage) {
+            throw new Error('Icon image should always be fetchable');
+        }
+
         return <img {...iconImage} alt="Icon" width={40} height={40} tw="mr-4" />;
     };
 
-    const [favicon, { fontFamily, fonts }] = await Promise.all([faviconLoader(), fontLoader()]);
+    const logoLoader = async () => {
+        if (!customization.header.logo) {
+            return null;
+        }
+
+        return await fetchImage(
+            useLightTheme ? customization.header.logo.light : customization.header.logo.dark
+        );
+    };
+
+    const [favicon, logo, { fontFamily, fonts }] = await Promise.all([
+        faviconLoader(),
+        logoLoader(),
+        fontLoader(),
+    ]);
 
     return new ImageResponse(
         <div
@@ -193,22 +211,14 @@ export async function serveOGImage(baseContext: GitBookSiteContext, params: Page
             />
 
             {/* Logo */}
-            {customization.header.logo ? (
+            {logo ? (
                 <div tw="flex flex-row">
-                    <img
-                        {...(await fetchImage(
-                            useLightTheme
-                                ? customization.header.logo.light
-                                : customization.header.logo.dark
-                        ))}
-                        alt="Logo"
-                        tw="h-[60px]"
-                    />
+                    <img {...logo} alt="Logo" tw="h-[60px]" />
                 </div>
             ) : (
                 <div tw="flex">
                     {favicon}
-                    <h3 tw="text-4xl my-0 font-bold">{contentTitle}</h3>
+                    <h3 tw="text-4xl my-0 font-bold">{site.title}</h3>
                 </div>
             )}
 
@@ -295,7 +305,9 @@ async function loadCustomFont(input: { url: string; weight: 400 | 700 }) {
 // biome-ignore lint/suspicious/noExplicitAny: <explanation>
 const staticCache = new Map<string, any>();
 
-// Do we need to limit the in-memory cache size? I think given the usage, we should be fine.
+/**
+ * Get or initialize a value in the static cache.
+ */
 async function getWithCache<T>(key: string, fn: () => Promise<T>) {
     const cached = staticCache.get(key) as T;
     if (cached) {
@@ -311,19 +323,46 @@ async function getWithCache<T>(key: string, fn: () => Promise<T>) {
  * Read a static image and cache it in memory.
  */
 async function fetchStaticImage(url: string) {
-    return getWithCache(`static-image:${url}`, () => fetchImage(url));
+    return getWithCache(`static-image:${url}`, async () => {
+        const image = await fetchImage(url);
+        if (!image) {
+            throw new Error('Failed to fetch static image');
+        }
+
+        return image;
+    });
 }
 
+/**
+ * @vercel/og supports the following image formats:
+ * Extracted from https://github.com/vercel/next.js/blob/canary/packages/next/src/compiled/%40vercel/og/index.node.js
+ */
+const UNSUPPORTED_IMAGE_EXTENSIONS = ['.avif', '.webp'];
+const SUPPORTED_IMAGE_TYPES = [
+    'image/png',
+    'image/apng',
+    'image/jpeg',
+    'image/gif',
+    'image/svg+xml',
+];
+
 /**
  * Fetch an image from a URL and return a base64 encoded string.
  * We do this as @vercel/og is otherwise failing on SVG images referenced by a URL.
  */
 async function fetchImage(url: string) {
+    // Skip early some images to avoid fetching them
+    const parsedURL = new URL(url);
+    if (UNSUPPORTED_IMAGE_EXTENSIONS.includes(getExtension(parsedURL.pathname).toLowerCase())) {
+        return null;
+    }
+
     const response = await fetch(url);
 
+    // Filter out unsupported image types
     const contentType = response.headers.get('content-type');
-    if (!contentType || !contentType.startsWith('image/')) {
-        throw new Error(`Invalid content type: ${contentType}`);
+    if (!contentType || !SUPPORTED_IMAGE_TYPES.some((type) => contentType.includes(type))) {
+        return null;
     }
 
     const arrayBuffer = await response.arrayBuffer();
@@ -334,8 +373,7 @@ async function fetchImage(url: string) {
     try {
         const { width, height } = imageSize(buffer);
         return { src, width, height };
-    } catch (error) {
-        console.error(`Error reading image size: ${error}`);
-        return { src };
+    } catch {
+        return null;
     }
 }

From 500c8cb649018c639c013a1c4850aaf000528122 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Samy=20Pess=C3=A9?= <samypesse@gmail.com>
Date: Tue, 17 Jun 2025 13:04:50 +0200
Subject: [PATCH 15/23] Don't crash ogimage generation on RTL text (#3341)

---
 .changeset/pink-windows-wonder.md       |  5 +++++
 bun.lock                                |  3 +++
 packages/gitbook/package.json           |  3 ++-
 packages/gitbook/src/routes/ogimage.tsx | 23 ++++++++++++++++++++---
 4 files changed, 30 insertions(+), 4 deletions(-)
 create mode 100644 .changeset/pink-windows-wonder.md

diff --git a/.changeset/pink-windows-wonder.md b/.changeset/pink-windows-wonder.md
new file mode 100644
index 000000000..d8e9560dc
--- /dev/null
+++ b/.changeset/pink-windows-wonder.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Don't crash ogimage generation on RTL text, as a workaround until we can support it.
diff --git a/bun.lock b/bun.lock
index 94b4fc3a5..8afc0e702 100644
--- a/bun.lock
+++ b/bun.lock
@@ -85,6 +85,7 @@
         "assert-never": "^1.2.1",
         "bun-types": "^1.1.20",
         "classnames": "^2.5.1",
+        "direction": "^2.0.1",
         "event-iterator": "^2.0.0",
         "framer-motion": "^10.16.14",
         "image-size": "^2.0.2",
@@ -1708,6 +1709,8 @@
 
     "dir-glob": ["dir-glob@3.0.1", "", { "dependencies": { "path-type": "^4.0.0" } }, "sha512-WkrWp9GR4KXfKGYzOLmTuGVi1UWFfws377n9cc55/tb6DuqyF6pcQ5AbiHEshaDpY9v6oaSr2XCDidGmMwdzIA=="],
 
+    "direction": ["direction@2.0.1", "", { "bin": { "direction": "cli.js" } }, "sha512-9S6m9Sukh1cZNknO1CWAr2QAWsbKLafQiyM5gZ7VgXHeuaoUwffKN4q6NC4A/Mf9iiPlOXQEKW/Mv/mh9/3YFA=="],
+
     "dlv": ["dlv@1.1.3", "", {}, "sha512-+HlytyjlPKnIG8XuRG8WvmBP8xs8P71y+SKKS6ZXWoEgLuePxtDoUEiH7WkdePWrQ5JBpE6aoVqfZfJUQkjXwA=="],
 
     "dom-serializer": ["dom-serializer@2.0.0", "", { "dependencies": { "domelementtype": "^2.3.0", "domhandler": "^5.0.2", "entities": "^4.2.0" } }, "sha512-wIkAryiqt/nV5EQKqQpo3SToSOV9J0DnbJqwK7Wv/Trc92zIAYZ4FlMu+JPFW1DfGFt81ZTCGgDEabffXeLyJg=="],
diff --git a/packages/gitbook/package.json b/packages/gitbook/package.json
index 2be76259d..e54901316 100644
--- a/packages/gitbook/package.json
+++ b/packages/gitbook/package.json
@@ -82,7 +82,8 @@
         "zod": "^3.24.2",
         "zod-to-json-schema": "^3.24.5",
         "zustand": "^5.0.3",
-        "image-size": "^2.0.2"
+        "image-size": "^2.0.2",
+        "direction": "^2.0.1"
     },
     "devDependencies": {
         "@argos-ci/playwright": "^5.0.3",
diff --git a/packages/gitbook/src/routes/ogimage.tsx b/packages/gitbook/src/routes/ogimage.tsx
index 4035f54be..6ce776c69 100644
--- a/packages/gitbook/src/routes/ogimage.tsx
+++ b/packages/gitbook/src/routes/ogimage.tsx
@@ -1,6 +1,7 @@
 import { CustomizationDefaultFont, CustomizationHeaderPreset } from '@gitbook/api';
 import { colorContrast } from '@gitbook/colors';
 import { type FontWeight, getDefaultFont } from '@gitbook/fonts';
+import { direction } from 'direction';
 import { imageSize } from 'image-size';
 import { redirect } from 'next/navigation';
 import { ImageResponse } from 'next/og';
@@ -218,7 +219,7 @@ export async function serveOGImage(baseContext: GitBookSiteContext, params: Page
             ) : (
                 <div tw="flex">
                     {favicon}
-                    <h3 tw="text-4xl my-0 font-bold">{site.title}</h3>
+                    <h3 tw="text-4xl my-0 font-bold">{transformText(site.title)}</h3>
                 </div>
             )}
 
@@ -227,10 +228,12 @@ export async function serveOGImage(baseContext: GitBookSiteContext, params: Page
                 <h1
                     tw={`text-8xl my-0 tracking-tight leading-none text-left text-[${colors.title}] font-bold`}
                 >
-                    {pageTitle}
+                    {transformText(pageTitle)}
                 </h1>
                 {pageDescription ? (
-                    <h2 tw="text-4xl mb-0 mt-8 w-[75%] font-normal">{pageDescription}</h2>
+                    <h2 tw="text-4xl mb-0 mt-8 w-[75%] font-normal">
+                        {transformText(pageDescription)}
+                    </h2>
                 ) : null}
             </div>
         </div>,
@@ -377,3 +380,17 @@ async function fetchImage(url: string) {
         return null;
     }
 }
+
+/**
+ * @vercel/og doesn't support RTL text, so we need to transform with a HACK for now.
+ * We can remove it once support has been added.
+ * https://github.com/vercel/satori/issues/74
+ */
+function transformText(text: string) {
+    const dir = direction(text);
+    if (dir !== 'rtl') {
+        return text;
+    }
+
+    return '';
+}

From ff6d1150a5930ffd79144e05882dd9c5cea78684 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Samy=20Pess=C3=A9?= <samypesse@gmail.com>
Date: Tue, 17 Jun 2025 16:12:58 +0200
Subject: [PATCH 16/23] Use `getRevisionPageDocument` on v2 (#3342)

---
 packages/gitbook-v2/src/lib/data/pages.ts | 35 ++---------------------
 1 file changed, 2 insertions(+), 33 deletions(-)

diff --git a/packages/gitbook-v2/src/lib/data/pages.ts b/packages/gitbook-v2/src/lib/data/pages.ts
index b9e3cabc5..319c0a917 100644
--- a/packages/gitbook-v2/src/lib/data/pages.ts
+++ b/packages/gitbook-v2/src/lib/data/pages.ts
@@ -1,4 +1,4 @@
-import { waitUntil } from '@/lib/waitUntil';
+import { isV2 } from '@/lib/v2';
 import type { JSONDocument, RevisionPageDocument } from '@gitbook/api';
 import type { GitBookSiteContext, GitBookSpaceContext } from '../context';
 import { getDataOrNull } from './errors';
@@ -12,10 +12,7 @@ export async function getPageDocument(
 ): Promise<JSONDocument | null> {
     const { dataFetcher, space } = context;
 
-    if (
-        'site' in context &&
-        (context.site.id === 'site_JOVzv' || context.site.id === 'site_IxAYj')
-    ) {
+    if (isV2()) {
         return getDataOrNull(
             dataFetcher.getRevisionPageDocument({
                 spaceId: space.id,
@@ -41,33 +38,5 @@ export async function getPageDocument(
         );
     }
 
-    // Pre-fetch the document to start filling the cache before we migrate to this API.
-    if (process.env.NODE_ENV === 'development') {
-        // Disable for now to investigate side-effects
-        if (isInPercentRollout(space.id, 10) || process.env.VERCEL_ENV === 'preview') {
-            await waitUntil(
-                getDataOrNull(
-                    dataFetcher.getRevisionPageDocument({
-                        spaceId: space.id,
-                        revisionId: space.revision,
-                        pageId: page.id,
-                    })
-                )
-            );
-        }
-    }
-
     return null;
 }
-
-function isInPercentRollout(value: string, rollout: number) {
-    return getRandomPercent(value) < rollout;
-}
-
-function getRandomPercent(value: string) {
-    const hash = value.split('').reduce((acc, char) => {
-        return acc + char.charCodeAt(0);
-    }, 0);
-
-    return hash % 100;
-}

From 67998b6f15b6977c7cc20dafe6a97f3156e95ffc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Samy=20Pess=C3=A9?= <samypesse@gmail.com>
Date: Tue, 17 Jun 2025 19:10:15 +0200
Subject: [PATCH 17/23] Fix ogimage generation failing with some JPEG images
 (#3345)

---
 .changeset/rare-pens-whisper.md               |  5 ++++
 .../src/lib/images/resizer/types.ts           |  2 +-
 packages/gitbook/src/routes/ogimage.tsx       | 25 ++++++++++++++++---
 3 files changed, 27 insertions(+), 5 deletions(-)
 create mode 100644 .changeset/rare-pens-whisper.md

diff --git a/.changeset/rare-pens-whisper.md b/.changeset/rare-pens-whisper.md
new file mode 100644
index 000000000..aed0712ba
--- /dev/null
+++ b/.changeset/rare-pens-whisper.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix ogimage generation failing with some JPEG images.
diff --git a/packages/gitbook-v2/src/lib/images/resizer/types.ts b/packages/gitbook-v2/src/lib/images/resizer/types.ts
index 8bbe697f9..9cb370586 100644
--- a/packages/gitbook-v2/src/lib/images/resizer/types.ts
+++ b/packages/gitbook-v2/src/lib/images/resizer/types.ts
@@ -13,7 +13,7 @@ export interface CloudflareImageJsonFormat {
  * https://developers.cloudflare.com/images/image-resizing/resize-with-workers/
  */
 export interface CloudflareImageOptions {
-    format?: 'webp' | 'avif' | 'json' | 'jpeg';
+    format?: 'webp' | 'avif' | 'json' | 'jpeg' | 'png';
     fit?: 'scale-down' | 'contain' | 'cover' | 'crop' | 'pad';
     width?: number;
     height?: number;
diff --git a/packages/gitbook/src/routes/ogimage.tsx b/packages/gitbook/src/routes/ogimage.tsx
index 6ce776c69..ce3f8a7d6 100644
--- a/packages/gitbook/src/routes/ogimage.tsx
+++ b/packages/gitbook/src/routes/ogimage.tsx
@@ -13,7 +13,13 @@ import { getExtension } from '@/lib/paths';
 import { filterOutNullable } from '@/lib/typescript';
 import { getCacheTag } from '@gitbook/cache-tags';
 import type { GitBookSiteContext } from '@v2/lib/context';
-import { getResizedImageURL } from '@v2/lib/images';
+import {
+    type ResizeImageOptions,
+    SizableImageAction,
+    checkIsSizableImageURL,
+    getResizedImageURL,
+    resizeImage,
+} from '@v2/lib/images';
 
 /**
  * Render the OpenGraph image for a site content.
@@ -178,7 +184,10 @@ export async function serveOGImage(baseContext: GitBookSiteContext, params: Page
         }
 
         return await fetchImage(
-            useLightTheme ? customization.header.logo.light : customization.header.logo.dark
+            useLightTheme ? customization.header.logo.light : customization.header.logo.dark,
+            {
+                height: 60,
+            }
         );
     };
 
@@ -353,14 +362,22 @@ const SUPPORTED_IMAGE_TYPES = [
  * Fetch an image from a URL and return a base64 encoded string.
  * We do this as @vercel/og is otherwise failing on SVG images referenced by a URL.
  */
-async function fetchImage(url: string) {
+async function fetchImage(url: string, options?: ResizeImageOptions) {
     // Skip early some images to avoid fetching them
     const parsedURL = new URL(url);
     if (UNSUPPORTED_IMAGE_EXTENSIONS.includes(getExtension(parsedURL.pathname).toLowerCase())) {
         return null;
     }
 
-    const response = await fetch(url);
+    // We use the image resizer to normalize the image format to PNG.
+    // as @vercel/og can sometimes fail on some JPEG images.
+    const response =
+        checkIsSizableImageURL(url) !== SizableImageAction.Resize
+            ? await fetch(url)
+            : await resizeImage(url, {
+                  ...options,
+                  format: 'png',
+              });
 
     // Filter out unsupported image types
     const contentType = response.headers.get('content-type');

From 88a35ed057935489519086295379eb2aef065cf9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Samy=20Pess=C3=A9?= <samypesse@gmail.com>
Date: Tue, 17 Jun 2025 19:23:52 +0200
Subject: [PATCH 18/23] Fix crash when integration is triggering invalid
 requests (#3346)

---
 .changeset/khaki-bees-count.md                        |  5 +++++
 .../src/components/DocumentView/Integration/render.ts | 11 +++++++----
 2 files changed, 12 insertions(+), 4 deletions(-)
 create mode 100644 .changeset/khaki-bees-count.md

diff --git a/.changeset/khaki-bees-count.md b/.changeset/khaki-bees-count.md
new file mode 100644
index 000000000..a481690e2
--- /dev/null
+++ b/.changeset/khaki-bees-count.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix crash when integration is triggering invalid requests.
diff --git a/packages/gitbook/src/components/DocumentView/Integration/render.ts b/packages/gitbook/src/components/DocumentView/Integration/render.ts
index a9a86c9e5..4e683e0dc 100644
--- a/packages/gitbook/src/components/DocumentView/Integration/render.ts
+++ b/packages/gitbook/src/components/DocumentView/Integration/render.ts
@@ -21,10 +21,13 @@ export async function fetchSafeIntegrationUI(
             request,
         }),
 
-        // The API can respond with a 400 error if the integration is not installed
-        // and 404 if the integration is not found.
-        // The API can also respond with a 502 error if the integration is not generating a proper response.
-        [404, 400, 502]
+        // The API can respond with certain errors that are expected to happen.
+        [
+            404, // Integration has been uninstalled
+            400, // Integration is rejecting its own request
+            422, // Integration is triggering an invalid request, failing at the validation step
+            502, // Integration is failing in an unexpected way
+        ]
     );
 
     return output;

From a3a944d7ddde5290fe9f070c0461c5884c75db49 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Samy=20Pess=C3=A9?= <samypesse@gmail.com>
Date: Tue, 17 Jun 2025 19:38:47 +0200
Subject: [PATCH 19/23] Fix crash during rendering of ogimage for VA sites with
 default icon (#3347)

---
 .changeset/thick-cups-shout.md          |  5 +++
 packages/gitbook/src/routes/icon.tsx    | 53 +++++++++++++++++--------
 packages/gitbook/src/routes/ogimage.tsx | 51 +++++++++++++-----------
 3 files changed, 69 insertions(+), 40 deletions(-)
 create mode 100644 .changeset/thick-cups-shout.md

diff --git a/.changeset/thick-cups-shout.md b/.changeset/thick-cups-shout.md
new file mode 100644
index 000000000..3aabb9ad4
--- /dev/null
+++ b/.changeset/thick-cups-shout.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix crash during rendering of ogimage for VA sites with default icon.
diff --git a/packages/gitbook/src/routes/icon.tsx b/packages/gitbook/src/routes/icon.tsx
index 03a6f3522..ab3429d63 100644
--- a/packages/gitbook/src/routes/icon.tsx
+++ b/packages/gitbook/src/routes/icon.tsx
@@ -24,6 +24,11 @@ const SIZES = {
     },
 };
 
+type RenderIconOptions = {
+    size: keyof typeof SIZES;
+    theme: 'light' | 'dark';
+};
+
 /**
  * Generate an icon for a site content.
  */
@@ -31,7 +36,7 @@ export async function serveIcon(context: GitBookSiteContext, req: Request) {
     const options = getOptions(req.url);
     const size = SIZES[options.size];
 
-    const { site, customization } = context;
+    const { customization } = context;
     const customIcon = 'icon' in customization.favicon ? customization.favicon.icon : null;
 
     // If the site has a custom icon, redirect to it
@@ -45,17 +50,45 @@ export async function serveIcon(context: GitBookSiteContext, req: Request) {
         );
     }
 
+    return new ImageResponse(<SiteDefaultIcon context={context} options={options} />, {
+        width: size.width,
+        height: size.height,
+        headers: {
+            'cache-tag': [
+                getCacheTag({
+                    tag: 'site',
+                    site: context.site.id,
+                }),
+            ].join(','),
+        },
+    });
+}
+
+/**
+ * Render the icon as a React node.
+ */
+export function SiteDefaultIcon(props: {
+    context: GitBookSiteContext;
+    options: RenderIconOptions;
+    style?: React.CSSProperties;
+    tw?: string;
+}) {
+    const { context, options, style, tw } = props;
+    const size = SIZES[options.size];
+
+    const { site, customization } = context;
     const contentTitle = site.title;
 
-    return new ImageResponse(
+    return (
         <div
-            tw={tcls(options.theme === 'light' ? 'bg-white' : 'bg-black', size.boxStyle)}
+            tw={tcls(options.theme === 'light' ? 'bg-white' : 'bg-black', size.boxStyle, tw)}
             style={{
                 width: '100%',
                 height: '100%',
                 display: 'flex',
                 alignItems: 'center',
                 justifyContent: 'center',
+                ...style,
             }}
         >
             <h2
@@ -70,19 +103,7 @@ export async function serveIcon(context: GitBookSiteContext, req: Request) {
                     ? getEmojiForCode(customization.favicon.emoji)
                     : contentTitle.slice(0, 1).toUpperCase()}
             </h2>
-        </div>,
-        {
-            width: size.width,
-            height: size.height,
-            headers: {
-                'cache-tag': [
-                    getCacheTag({
-                        tag: 'site',
-                        site: context.site.id,
-                    }),
-                ].join(','),
-            },
-        }
+        </div>
     );
 }
 
diff --git a/packages/gitbook/src/routes/ogimage.tsx b/packages/gitbook/src/routes/ogimage.tsx
index ce3f8a7d6..f79b86948 100644
--- a/packages/gitbook/src/routes/ogimage.tsx
+++ b/packages/gitbook/src/routes/ogimage.tsx
@@ -20,13 +20,14 @@ import {
     getResizedImageURL,
     resizeImage,
 } from '@v2/lib/images';
+import { SiteDefaultIcon } from './icon';
 
 /**
  * Render the OpenGraph image for a site content.
  */
 export async function serveOGImage(baseContext: GitBookSiteContext, params: PageParams) {
     const { context, pageTarget } = await fetchPageData(baseContext, params);
-    const { customization, site, linker, imageResizer } = context;
+    const { customization, site, imageResizer } = context;
     const page = pageTarget?.page;
 
     // If user configured a custom social preview, we redirect to it.
@@ -148,34 +149,36 @@ export async function serveOGImage(baseContext: GitBookSiteContext, params: Page
     }
 
     const faviconLoader = async () => {
+        if (customization.header.logo) {
+            // Don't load the favicon if we have a logo
+            // as it'll not be used.
+            return null;
+        }
+
+        const faviconSize = {
+            width: 48,
+            height: 48,
+        };
+
         if ('icon' in customization.favicon)
             return (
                 <img
-                    src={customization.favicon.icon[theme]}
-                    width={40}
-                    height={40}
-                    tw="mr-4"
+                    {...(await fetchImage(customization.favicon.icon[theme], faviconSize))}
+                    {...faviconSize}
                     alt="Icon"
                 />
             );
-        if ('emoji' in customization.favicon)
-            return (
-                <span tw="text-4xl mr-4">
-                    {String.fromCodePoint(Number.parseInt(`0x${customization.favicon.emoji}`))}
-                </span>
-            );
-        const iconImage = await fetchImage(
-            linker.toAbsoluteURL(
-                linker.toPathInSpace(
-                    `~gitbook/icon?size=medium&theme=${customization.themes.default}`
-                )
-            )
-        );
-        if (!iconImage) {
-            throw new Error('Icon image should always be fetchable');
-        }
 
-        return <img {...iconImage} alt="Icon" width={40} height={40} tw="mr-4" />;
+        return (
+            <SiteDefaultIcon
+                context={context}
+                options={{
+                    size: 'small',
+                    theme,
+                }}
+                style={faviconSize}
+            />
+        );
     };
 
     const logoLoader = async () => {
@@ -226,9 +229,9 @@ export async function serveOGImage(baseContext: GitBookSiteContext, params: Page
                     <img {...logo} alt="Logo" tw="h-[60px]" />
                 </div>
             ) : (
-                <div tw="flex">
+                <div tw="flex flex-row items-center">
                     {favicon}
-                    <h3 tw="text-4xl my-0 font-bold">{transformText(site.title)}</h3>
+                    <h3 tw="text-4xl ml-4 my-0 font-bold">{transformText(site.title)}</h3>
                 </div>
             )}
 

From 8f7c304d5852ecdeb556085f211c4369bd861b2c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Samy=20Pess=C3=A9?= <samypesse@gmail.com>
Date: Tue, 17 Jun 2025 20:25:21 +0200
Subject: [PATCH 20/23] Fix crash when rendering ogimage with invalid icon
 (#3348)

---
 packages/gitbook/src/routes/ogimage.tsx | 14 ++++++--------
 1 file changed, 6 insertions(+), 8 deletions(-)

diff --git a/packages/gitbook/src/routes/ogimage.tsx b/packages/gitbook/src/routes/ogimage.tsx
index f79b86948..4d8a83b2c 100644
--- a/packages/gitbook/src/routes/ogimage.tsx
+++ b/packages/gitbook/src/routes/ogimage.tsx
@@ -160,14 +160,12 @@ export async function serveOGImage(baseContext: GitBookSiteContext, params: Page
             height: 48,
         };
 
-        if ('icon' in customization.favicon)
-            return (
-                <img
-                    {...(await fetchImage(customization.favicon.icon[theme], faviconSize))}
-                    {...faviconSize}
-                    alt="Icon"
-                />
-            );
+        if ('icon' in customization.favicon) {
+            const faviconImage = await fetchImage(customization.favicon.icon[theme], faviconSize);
+            if (faviconImage) {
+                return <img {...faviconImage} {...faviconSize} alt="Icon" />;
+            }
+        }
 
         return (
             <SiteDefaultIcon

From b4918f60cebccb4660a2a32a738f513eba83f0e3 Mon Sep 17 00:00:00 2001
From: conico974 <nicodorseuil@yahoo.fr>
Date: Tue, 17 Jun 2025 22:31:32 +0200
Subject: [PATCH 21/23] fix variant space change when pathname equals
 space-path (#3343)

Co-authored-by: Nicolas Dorseuil <nicolas@gitbook.io>
---
 .../src/components/Header/SpacesDropdown.tsx  | 21 ++++-----
 .../Header/SpacesDropdownMenuItem.tsx         | 45 +++++++++++++++++--
 2 files changed, 50 insertions(+), 16 deletions(-)

diff --git a/packages/gitbook/src/components/Header/SpacesDropdown.tsx b/packages/gitbook/src/components/Header/SpacesDropdown.tsx
index dd6887d95..87ad44b5d 100644
--- a/packages/gitbook/src/components/Header/SpacesDropdown.tsx
+++ b/packages/gitbook/src/components/Header/SpacesDropdown.tsx
@@ -4,7 +4,7 @@ import { getSiteSpaceURL } from '@/lib/sites';
 import { tcls } from '@/lib/tailwind';
 import type { GitBookSiteContext } from '@v2/lib/context';
 import { DropdownChevron, DropdownMenu } from './DropdownMenu';
-import { SpacesDropdownMenuItem } from './SpacesDropdownMenuItem';
+import { SpacesDropdownMenuItems } from './SpacesDropdownMenuItem';
 
 export function SpacesDropdown(props: {
     context: GitBookSiteContext;
@@ -65,17 +65,14 @@ export function SpacesDropdown(props: {
                 </div>
             }
         >
-            {siteSpaces.map((otherSiteSpace, index) => (
-                <SpacesDropdownMenuItem
-                    key={`${otherSiteSpace.id}-${index}`}
-                    variantSpace={{
-                        id: otherSiteSpace.id,
-                        title: otherSiteSpace.title,
-                        url: getSiteSpaceURL(context, otherSiteSpace),
-                    }}
-                    active={otherSiteSpace.id === siteSpace.id}
-                />
-            ))}
+            <SpacesDropdownMenuItems
+                slimSpaces={siteSpaces.map((space) => ({
+                    id: space.id,
+                    title: space.title,
+                    url: getSiteSpaceURL(context, space),
+                }))}
+                curPath={siteSpace.path}
+            />
         </DropdownMenu>
     );
 }
diff --git a/packages/gitbook/src/components/Header/SpacesDropdownMenuItem.tsx b/packages/gitbook/src/components/Header/SpacesDropdownMenuItem.tsx
index 70859abfa..2044d0fc6 100644
--- a/packages/gitbook/src/components/Header/SpacesDropdownMenuItem.tsx
+++ b/packages/gitbook/src/components/Header/SpacesDropdownMenuItem.tsx
@@ -6,12 +6,28 @@ import { joinPath } from '@/lib/paths';
 import { useCurrentPagePath } from '../hooks';
 import { DropdownMenuItem } from './DropdownMenu';
 
-function useVariantSpaceHref(variantSpaceUrl: string) {
+interface VariantSpace {
+    id: Space['id'];
+    title: Space['title'];
+    url: string;
+}
+
+// When switching to a different variant space, we reconstruct the URL by swapping the space path.
+function useVariantSpaceHref(variantSpaceUrl: string, currentSpacePath: string, active = false) {
     const currentPathname = useCurrentPagePath();
 
+    // We need to ensure that the variant space URL is not the same as the current space path.
+    // If it is, we return only the variant space URL to redirect to the root of the variant space.
+    // This is necessary in case the currentPathname is the same as the variantSpaceUrl,
+    // otherwise we would redirect to the same space if the variant space that we are switching to is the default one.
+    if (!active && currentPathname.startsWith(`${currentSpacePath}/`)) {
+        return variantSpaceUrl;
+    }
+
     if (URL.canParse(variantSpaceUrl)) {
         const targetUrl = new URL(variantSpaceUrl);
         targetUrl.pathname = joinPath(targetUrl.pathname, currentPathname);
+
         targetUrl.searchParams.set('fallback', 'true');
 
         return targetUrl.toString();
@@ -22,11 +38,12 @@ function useVariantSpaceHref(variantSpaceUrl: string) {
 }
 
 export function SpacesDropdownMenuItem(props: {
-    variantSpace: { id: Space['id']; title: Space['title']; url: string };
+    variantSpace: VariantSpace;
     active: boolean;
+    currentSpacePath: string;
 }) {
-    const { variantSpace, active } = props;
-    const variantHref = useVariantSpaceHref(variantSpace.url);
+    const { variantSpace, active, currentSpacePath } = props;
+    const variantHref = useVariantSpaceHref(variantSpace.url, currentSpacePath, active);
 
     return (
         <DropdownMenuItem key={variantSpace.id} href={variantHref} active={active}>
@@ -34,3 +51,23 @@ export function SpacesDropdownMenuItem(props: {
         </DropdownMenuItem>
     );
 }
+
+export function SpacesDropdownMenuItems(props: {
+    slimSpaces: VariantSpace[];
+    curPath: string;
+}) {
+    const { slimSpaces, curPath } = props;
+
+    return (
+        <>
+            {slimSpaces.map((space) => (
+                <SpacesDropdownMenuItem
+                    key={space.id}
+                    variantSpace={space}
+                    active={false}
+                    currentSpacePath={curPath}
+                />
+            ))}
+        </>
+    );
+}

From 392f59450caee52d07bc6b59a0c2934df1cd23e1 Mon Sep 17 00:00:00 2001
From: Steven H <steven@gitbook.io>
Date: Wed, 18 Jun 2025 12:15:45 +0100
Subject: [PATCH 22/23] Improve performance of InlineLinkTooltip (#3339)

---
 .changeset/soft-walls-change.md               |   6 +
 .../components/DocumentView/DocumentView.tsx  |   8 +
 .../components/DocumentView/InlineLink.tsx    |  61 -------
 .../DocumentView/InlineLink/InlineLink.tsx    | 153 ++++++++++++++++++
 .../InlineLink/InlineLinkTooltip.tsx          |  73 +++++++++
 .../InlineLinkTooltipImpl.tsx}                | 101 ++++--------
 .../DocumentView/InlineLink/index.ts          |   1 +
 .../gitbook/src/components/PDF/PDFPage.tsx    |   1 +
 .../src/components/PageBody/PageBody.tsx      |  14 +-
 .../src/components/Search/server-actions.tsx  |   1 +
 packages/gitbook/src/lib/document.ts          |  35 ++++
 11 files changed, 325 insertions(+), 129 deletions(-)
 create mode 100644 .changeset/soft-walls-change.md
 delete mode 100644 packages/gitbook/src/components/DocumentView/InlineLink.tsx
 create mode 100644 packages/gitbook/src/components/DocumentView/InlineLink/InlineLink.tsx
 create mode 100644 packages/gitbook/src/components/DocumentView/InlineLink/InlineLinkTooltip.tsx
 rename packages/gitbook/src/components/DocumentView/{InlineLinkTooltip.tsx => InlineLink/InlineLinkTooltipImpl.tsx} (64%)
 create mode 100644 packages/gitbook/src/components/DocumentView/InlineLink/index.ts

diff --git a/.changeset/soft-walls-change.md b/.changeset/soft-walls-change.md
new file mode 100644
index 000000000..2086de031
--- /dev/null
+++ b/.changeset/soft-walls-change.md
@@ -0,0 +1,6 @@
+---
+"gitbook": patch
+"gitbook-v2": patch
+---
+
+Fix InlineLinkTooltip having a negative impact on performance, especially on larger pages.
diff --git a/packages/gitbook/src/components/DocumentView/DocumentView.tsx b/packages/gitbook/src/components/DocumentView/DocumentView.tsx
index 724a7f2b0..1ff8542ee 100644
--- a/packages/gitbook/src/components/DocumentView/DocumentView.tsx
+++ b/packages/gitbook/src/components/DocumentView/DocumentView.tsx
@@ -28,6 +28,14 @@ export interface DocumentContext {
      * @default true
      */
     wrapBlocksInSuspense?: boolean;
+
+    /**
+     * True if link previews should be rendered.
+     * This is used to limit the number of link previews rendered in a document.
+     * If false, no link previews will be rendered.
+     * @default false
+     */
+    shouldRenderLinkPreviews?: boolean;
 }
 
 export interface DocumentContextProps {
diff --git a/packages/gitbook/src/components/DocumentView/InlineLink.tsx b/packages/gitbook/src/components/DocumentView/InlineLink.tsx
deleted file mode 100644
index f5bd7f798..000000000
--- a/packages/gitbook/src/components/DocumentView/InlineLink.tsx
+++ /dev/null
@@ -1,61 +0,0 @@
-import { type DocumentInlineLink, SiteInsightsLinkPosition } from '@gitbook/api';
-
-import { resolveContentRef } from '@/lib/references';
-import { Icon } from '@gitbook/icons';
-import { StyledLink } from '../primitives';
-import type { InlineProps } from './Inline';
-import { InlineLinkTooltip } from './InlineLinkTooltip';
-import { Inlines } from './Inlines';
-
-export async function InlineLink(props: InlineProps<DocumentInlineLink>) {
-    const { inline, document, context, ancestorInlines } = props;
-
-    const resolved = context.contentContext
-        ? await resolveContentRef(inline.data.ref, context.contentContext, {
-              // We don't want to resolve the anchor text here, as it can be very expensive and will block rendering if there is a lot of anchors link.
-              resolveAnchorText: false,
-          })
-        : null;
-
-    if (!context.contentContext || !resolved) {
-        return (
-            <span title="Broken link" className="underline">
-                <Inlines
-                    context={context}
-                    document={document}
-                    nodes={inline.nodes}
-                    ancestorInlines={[...ancestorInlines, inline]}
-                />
-            </span>
-        );
-    }
-    const isExternal = inline.data.ref.kind === 'url';
-
-    return (
-        <InlineLinkTooltip inline={inline} context={context.contentContext} resolved={resolved}>
-            <StyledLink
-                href={resolved.href}
-                insights={{
-                    type: 'link_click',
-                    link: {
-                        target: inline.data.ref,
-                        position: SiteInsightsLinkPosition.Content,
-                    },
-                }}
-            >
-                <Inlines
-                    context={context}
-                    document={document}
-                    nodes={inline.nodes}
-                    ancestorInlines={[...ancestorInlines, inline]}
-                />
-                {isExternal ? (
-                    <Icon
-                        icon="arrow-up-right"
-                        className="ml-0.5 inline size-3 links-accent:text-tint-subtle"
-                    />
-                ) : null}
-            </StyledLink>
-        </InlineLinkTooltip>
-    );
-}
diff --git a/packages/gitbook/src/components/DocumentView/InlineLink/InlineLink.tsx b/packages/gitbook/src/components/DocumentView/InlineLink/InlineLink.tsx
new file mode 100644
index 000000000..8ad287a35
--- /dev/null
+++ b/packages/gitbook/src/components/DocumentView/InlineLink/InlineLink.tsx
@@ -0,0 +1,153 @@
+import { type DocumentInlineLink, SiteInsightsLinkPosition } from '@gitbook/api';
+
+import { getSpaceLanguage, tString } from '@/intl/server';
+import { languages } from '@/intl/translations';
+import { type ResolvedContentRef, resolveContentRef } from '@/lib/references';
+import { Icon } from '@gitbook/icons';
+import type { GitBookAnyContext } from '@v2/lib/context';
+import { StyledLink } from '../../primitives';
+import type { InlineProps } from '../Inline';
+import { Inlines } from '../Inlines';
+import { InlineLinkTooltip } from './InlineLinkTooltip';
+
+export async function InlineLink(props: InlineProps<DocumentInlineLink>) {
+    const { inline, document, context, ancestorInlines } = props;
+
+    const resolved = context.contentContext
+        ? await resolveContentRef(inline.data.ref, context.contentContext, {
+              // We don't want to resolve the anchor text here, as it can be very expensive and will block rendering if there is a lot of anchors link.
+              resolveAnchorText: false,
+          })
+        : null;
+
+    if (!context.contentContext || !resolved) {
+        return (
+            <span title="Broken link" className="underline">
+                <Inlines
+                    context={context}
+                    document={document}
+                    nodes={inline.nodes}
+                    ancestorInlines={[...ancestorInlines, inline]}
+                />
+            </span>
+        );
+    }
+    const isExternal = inline.data.ref.kind === 'url';
+    const content = (
+        <StyledLink
+            href={resolved.href}
+            insights={{
+                type: 'link_click',
+                link: {
+                    target: inline.data.ref,
+                    position: SiteInsightsLinkPosition.Content,
+                },
+            }}
+        >
+            <Inlines
+                context={context}
+                document={document}
+                nodes={inline.nodes}
+                ancestorInlines={[...ancestorInlines, inline]}
+            />
+            {isExternal ? (
+                <Icon
+                    icon="arrow-up-right"
+                    className="ml-0.5 inline size-3 links-accent:text-tint-subtle"
+                />
+            ) : null}
+        </StyledLink>
+    );
+
+    if (context.shouldRenderLinkPreviews) {
+        return (
+            <InlineLinkTooltipWrapper
+                inline={inline}
+                context={context.contentContext}
+                resolved={resolved}
+            >
+                {content}
+            </InlineLinkTooltipWrapper>
+        );
+    }
+
+    return content;
+}
+
+/**
+ * An SSR component that renders a link with a tooltip.
+ * Essentially it pulls the minimum amount of props from the context to render the tooltip.
+ */
+function InlineLinkTooltipWrapper(props: {
+    inline: DocumentInlineLink;
+    context: GitBookAnyContext;
+    children: React.ReactNode;
+    resolved: ResolvedContentRef;
+}) {
+    const { inline, context, resolved, children } = props;
+
+    let breadcrumbs = resolved.ancestors ?? [];
+    const language =
+        'customization' in context ? getSpaceLanguage(context.customization) : languages.en;
+    const isExternal = inline.data.ref.kind === 'url';
+    const isSamePage = inline.data.ref.kind === 'anchor' && inline.data.ref.page === undefined;
+    if (isExternal) {
+        breadcrumbs = [
+            {
+                label: tString(language, 'link_tooltip_external_link'),
+            },
+        ];
+    }
+    if (isSamePage) {
+        breadcrumbs = [
+            {
+                label: tString(language, 'link_tooltip_page_anchor'),
+                icon: <Icon icon="arrow-down-short-wide" className="size-3" />,
+            },
+        ];
+        resolved.subText = undefined;
+    }
+
+    const aiSummary: { pageId: string; spaceId: string } | undefined = (() => {
+        if (isExternal) {
+            return;
+        }
+
+        if (isSamePage) {
+            return;
+        }
+
+        if (!('customization' in context) || !context.customization.ai?.pageLinkSummaries.enabled) {
+            return;
+        }
+
+        if (!('page' in context) || !('page' in inline.data.ref)) {
+            return;
+        }
+
+        if (inline.data.ref.kind === 'page' || inline.data.ref.kind === 'anchor') {
+            return {
+                pageId: resolved.page?.id ?? inline.data.ref.page ?? context.page.id,
+                spaceId: inline.data.ref.space ?? context.space.id,
+            };
+        }
+    })();
+
+    return (
+        <InlineLinkTooltip
+            breadcrumbs={breadcrumbs}
+            isExternal={isExternal}
+            isSamePage={isSamePage}
+            aiSummary={aiSummary}
+            openInNewTabLabel={tString(language, 'open_in_new_tab')}
+            target={{
+                href: resolved.href,
+                text: resolved.text,
+                subText: resolved.subText,
+                icon: resolved.icon,
+            }}
+        >
+            {children}
+        </InlineLinkTooltip>
+    );
+}
diff --git a/packages/gitbook/src/components/DocumentView/InlineLink/InlineLinkTooltip.tsx b/packages/gitbook/src/components/DocumentView/InlineLink/InlineLinkTooltip.tsx
new file mode 100644
index 000000000..45be0c717
--- /dev/null
+++ b/packages/gitbook/src/components/DocumentView/InlineLink/InlineLinkTooltip.tsx
@@ -0,0 +1,73 @@
+'use client';
+import dynamic from 'next/dynamic';
+import React from 'react';
+
+const LoadingValueContext = React.createContext<React.ReactNode>(null);
+
+// To avoid polluting the RSC payload with the tooltip implementation,
+// we lazily load it on the client side. This way, the tooltip is only loaded
+// when the user interacts with the link, and it doesn't block the initial render.
+
+const InlineLinkTooltipImpl = dynamic(
+    () => import('./InlineLinkTooltipImpl').then((mod) => mod.InlineLinkTooltipImpl),
+    {
+        // Disable server-side rendering for this component, it's only
+        // visible on user interaction.
+        ssr: false,
+        loading: () => {
+            // The fallback should be the children (the content of the link),
+            // but as next/dynamic is aiming for feature parity with React.lazy,
+            // it doesn't support passing children to the loading component.
+            // https://github.com/vercel/next.js/issues/7906
+            const children = React.useContext(LoadingValueContext);
+            return <>{children}</>;
+        },
+    }
+);
+
+/**
+ * Tooltip for inline links. It's lazily loaded to avoid blocking the initial render
+ * and polluting the RSC payload.
+ *
+ * The link text and href have already been rendered on the server for good SEO,
+ * so we can be as lazy as possible with the tooltip.
+ */
+export function InlineLinkTooltip(props: {
+    isSamePage: boolean;
+    isExternal: boolean;
+    aiSummary?: { pageId: string; spaceId: string };
+    breadcrumbs: Array<{ href?: string; label: string; icon?: React.ReactNode }>;
+    target: {
+        href: string;
+        text: string;
+        subText?: string;
+        icon?: React.ReactNode;
+    };
+    openInNewTabLabel: string;
+    children: React.ReactNode;
+}) {
+    const { children, ...rest } = props;
+    const [shouldLoad, setShouldLoad] = React.useState(false);
+
+    // Once the browser is idle, we set shouldLoad to true.
+    // NOTE: to be slightly more performant, we could load when a link is hovered.
+    // But I found this was too much of a delay for the tooltip to appear.
+    // Loading on idle is a good compromise, as it allows the initial render to be fast,
+    // while still loading the tooltip in the background and not polluting the RSC payload.
+    React.useEffect(() => {
+        if ('requestIdleCallback' in window) {
+            (window as globalThis.Window).requestIdleCallback(() => setShouldLoad(true));
+        } else {
+            // fallback for old browsers
+            setTimeout(() => setShouldLoad(true), 2000);
+        }
+    }, []);
+
+    return shouldLoad ? (
+        <LoadingValueContext.Provider value={children}>
+            <InlineLinkTooltipImpl {...rest}>{children}</InlineLinkTooltipImpl>
+        </LoadingValueContext.Provider>
+    ) : (
+        children
+    );
+}
diff --git a/packages/gitbook/src/components/DocumentView/InlineLinkTooltip.tsx b/packages/gitbook/src/components/DocumentView/InlineLink/InlineLinkTooltipImpl.tsx
similarity index 64%
rename from packages/gitbook/src/components/DocumentView/InlineLinkTooltip.tsx
rename to packages/gitbook/src/components/DocumentView/InlineLink/InlineLinkTooltipImpl.tsx
index 1a5cefa1e..333184a2c 100644
--- a/packages/gitbook/src/components/DocumentView/InlineLinkTooltip.tsx
+++ b/packages/gitbook/src/components/DocumentView/InlineLink/InlineLinkTooltipImpl.tsx
@@ -1,55 +1,27 @@
-import type { DocumentInlineLink } from '@gitbook/api';
-
-import type { ResolvedContentRef } from '@/lib/references';
-
-import { getSpaceLanguage } from '@/intl/server';
-import { tString } from '@/intl/translate';
-import { languages } from '@/intl/translations';
-import { getNodeText } from '@/lib/document';
+'use client';
 import { tcls } from '@/lib/tailwind';
 import { Icon } from '@gitbook/icons';
 import * as Tooltip from '@radix-ui/react-tooltip';
-import type { GitBookAnyContext } from '@v2/lib/context';
 import { Fragment } from 'react';
-import { AIPageLinkSummary } from '../Adaptive/AIPageLinkSummary';
-import { Button, StyledLink } from '../primitives';
+import { AIPageLinkSummary } from '../../Adaptive';
+import { Button, StyledLink } from '../../primitives';
 
-export async function InlineLinkTooltip(props: {
-    inline: DocumentInlineLink;
-    context: GitBookAnyContext;
+export function InlineLinkTooltipImpl(props: {
+    isSamePage: boolean;
+    isExternal: boolean;
+    aiSummary?: { pageId: string; spaceId: string };
+    breadcrumbs: Array<{ href?: string; label: string; icon?: React.ReactNode }>;
+    target: {
+        href: string;
+        text: string;
+        subText?: string;
+        icon?: React.ReactNode;
+    };
+    openInNewTabLabel: string;
     children: React.ReactNode;
-    resolved: ResolvedContentRef;
 }) {
-    const { inline, context, resolved, children } = props;
-
-    let breadcrumbs = resolved.ancestors;
-    const language =
-        'customization' in context ? getSpaceLanguage(context.customization) : languages.en;
-    const isExternal = inline.data.ref.kind === 'url';
-    const isSamePage = inline.data.ref.kind === 'anchor' && inline.data.ref.page === undefined;
-    if (isExternal) {
-        breadcrumbs = [
-            {
-                label: tString(language, 'link_tooltip_external_link'),
-            },
-        ];
-    }
-    if (isSamePage) {
-        breadcrumbs = [
-            {
-                label: tString(language, 'link_tooltip_page_anchor'),
-                icon: <Icon icon="arrow-down-short-wide" className="size-3" />,
-            },
-        ];
-        resolved.subText = undefined;
-    }
-
-    const hasAISummary =
-        !isExternal &&
-        !isSamePage &&
-        'customization' in context &&
-        context.customization.ai?.pageLinkSummaries.enabled &&
-        (inline.data.ref.kind === 'page' || inline.data.ref.kind === 'anchor');
+    const { isSamePage, isExternal, aiSummary, openInNewTabLabel, target, breadcrumbs, children } =
+        props;
 
     return (
         <Tooltip.Provider delayDuration={200}>
@@ -100,15 +72,15 @@ export async function InlineLinkTooltip(props: {
                                                 isExternal && 'text-sm [overflow-wrap:anywhere]'
                                             )}
                                         >
-                                            {resolved.icon ? (
+                                            {target.icon ? (
                                                 <div className="mt-1 text-tint-subtle empty:hidden">
-                                                    {resolved.icon}
+                                                    {target.icon}
                                                 </div>
                                             ) : null}
-                                            <h5 className="font-semibold">{resolved.text}</h5>
+                                            <h5 className="font-semibold">{target.text}</h5>
                                         </div>
                                     </div>
-                                    {!isSamePage && resolved.href ? (
+                                    {!isSamePage && target.href ? (
                                         <Button
                                             className={tcls(
                                                 '-mx-2 -my-2 ml-auto',
@@ -117,40 +89,35 @@ export async function InlineLinkTooltip(props: {
                                                     : null
                                             )}
                                             variant="blank"
-                                            href={resolved.href}
+                                            href={target.href}
                                             target="_blank"
-                                            label={tString(language, 'open_in_new_tab')}
+                                            label={openInNewTabLabel}
                                             size="small"
                                             icon="arrow-up-right-from-square"
                                             iconOnly={true}
                                         />
                                     ) : null}
                                 </div>
-                                {resolved.subText ? (
-                                    <p className="mt-1 text-sm text-tint">{resolved.subText}</p>
+                                {target.subText ? (
+                                    <p className="mt-1 text-sm text-tint">{target.subText}</p>
                                 ) : null}
                             </div>
 
-                            {hasAISummary && 'page' in context && 'page' in inline.data.ref ? (
+                            {aiSummary ? (
                                 <div className="border-tint-subtle border-t bg-tint p-4">
                                     <AIPageLinkSummary
-                                        targetPageId={
-                                            resolved.page?.id ??
-                                            inline.data.ref.page ??
-                                            context.page.id
-                                        }
-                                        targetSpaceId={inline.data.ref.space ?? context.space.id}
-                                        linkTitle={getNodeText(inline)}
-                                        linkPreview={`**${resolved.text}**: ${resolved.subText}`}
-                                        showTrademark={
-                                            'customization' in context &&
-                                            context.customization.trademark.enabled
-                                        }
+                                        targetPageId={aiSummary.pageId}
+                                        targetSpaceId={aiSummary.spaceId}
+                                        showTrademark
                                     />
                                 </div>
                             ) : null}
                         </div>
-                        <Tooltip.Arrow className={hasAISummary ? 'fill-tint-3' : 'fill-tint-1'} />
+                        <Tooltip.Arrow
+                            className={
+                                typeof aiSummary !== 'undefined' ? 'fill-tint-3' : 'fill-tint-1'
+                            }
+                        />
                     </Tooltip.Content>
                 </Tooltip.Portal>
             </Tooltip.Root>
diff --git a/packages/gitbook/src/components/DocumentView/InlineLink/index.ts b/packages/gitbook/src/components/DocumentView/InlineLink/index.ts
new file mode 100644
index 000000000..1d7f30120
--- /dev/null
+++ b/packages/gitbook/src/components/DocumentView/InlineLink/index.ts
@@ -0,0 +1 @@
+export * from './InlineLink';
diff --git a/packages/gitbook/src/components/PDF/PDFPage.tsx b/packages/gitbook/src/components/PDF/PDFPage.tsx
index f70b340b4..cc9bf2807 100644
--- a/packages/gitbook/src/components/PDF/PDFPage.tsx
+++ b/packages/gitbook/src/components/PDF/PDFPage.tsx
@@ -245,6 +245,7 @@ async function PDFPageDocument(props: {
                             page,
                         },
                         getId: (id) => getPagePDFContainerId(page, id),
+                        shouldRenderLinkPreviews: false, // We don't want to render link previews in the PDF.
                     }}
                     // We consider all pages as offscreen in PDF mode
                     // to ensure we can efficiently render as many pages as possible
diff --git a/packages/gitbook/src/components/PageBody/PageBody.tsx b/packages/gitbook/src/components/PageBody/PageBody.tsx
index 801db03ce..9b9e74474 100644
--- a/packages/gitbook/src/components/PageBody/PageBody.tsx
+++ b/packages/gitbook/src/components/PageBody/PageBody.tsx
@@ -4,7 +4,7 @@ import React from 'react';
 
 import { getSpaceLanguage } from '@/intl/server';
 import { t } from '@/intl/translate';
-import { hasFullWidthBlock, isNodeEmpty } from '@/lib/document';
+import { hasFullWidthBlock, hasMoreThan, isNodeEmpty } from '@/lib/document';
 import type { AncestorRevisionPage } from '@/lib/pages';
 import { tcls } from '@/lib/tailwind';
 import { DocumentView, DocumentViewSkeleton } from '../DocumentView';
@@ -17,6 +17,8 @@ import { PageFooterNavigation } from './PageFooterNavigation';
 import { PageHeader } from './PageHeader';
 import { PreservePageLayout } from './PreservePageLayout';
 
+const LINK_PREVIEW_MAX_COUNT = 100;
+
 export function PageBody(props: {
     context: GitBookSiteContext;
     page: RevisionPageDocument;
@@ -28,6 +30,15 @@ export function PageBody(props: {
     const { customization } = context;
 
     const contentFullWidth = document ? hasFullWidthBlock(document) : false;
+
+    // Render link previews only if there are less than LINK_PREVIEW_MAX_COUNT links in the document.
+    const shouldRenderLinkPreviews = document
+        ? !hasMoreThan(
+              document,
+              (inline) => inline.object === 'inline' && inline.type === 'link',
+              LINK_PREVIEW_MAX_COUNT
+          )
+        : false;
     const pageFullWidth = page.id === 'wtthNFMqmEQmnt5LKR0q';
     const asFullWidth = pageFullWidth || contentFullWidth;
     const language = getSpaceLanguage(customization);
@@ -68,6 +79,7 @@ export function PageBody(props: {
                             context={{
                                 mode: 'default',
                                 contentContext: context,
+                                shouldRenderLinkPreviews,
                             }}
                         />
                     </React.Suspense>
diff --git a/packages/gitbook/src/components/Search/server-actions.tsx b/packages/gitbook/src/components/Search/server-actions.tsx
index b45bc0aba..9bd8257c1 100644
--- a/packages/gitbook/src/components/Search/server-actions.tsx
+++ b/packages/gitbook/src/components/Search/server-actions.tsx
@@ -345,6 +345,7 @@ async function transformAnswer(
                         mode: 'default',
                         contentContext: undefined,
                         wrapBlocksInSuspense: false,
+                        shouldRenderLinkPreviews: false, // We don't want to render link previews in the AI answer.
                     }}
                     style={['space-y-5']}
                 />
diff --git a/packages/gitbook/src/lib/document.ts b/packages/gitbook/src/lib/document.ts
index 33618f76c..8d9fabc1e 100644
--- a/packages/gitbook/src/lib/document.ts
+++ b/packages/gitbook/src/lib/document.ts
@@ -30,6 +30,41 @@ export function hasFullWidthBlock(document: JSONDocument): boolean {
     return false;
 }
 
+/**
+ * Returns true if the document has more than `limit` blocks and/or inlines that match the `check` predicate.
+ */
+export function hasMoreThan(
+    document: JSONDocument | DocumentBlock,
+    check: (block: DocumentBlock | DocumentInline) => boolean,
+    limit = 1
+): boolean {
+    let count = 0;
+
+    function traverse(node: JSONDocument | DocumentBlock | DocumentFragment): boolean {
+        for (const child of 'nodes' in node ? node.nodes : []) {
+            if (child.object === 'text') continue;
+
+            if (check(child)) {
+                count++;
+                if (count > limit) return true;
+            }
+
+            if (child.object === 'block' && 'nodes' in child) {
+                if (traverse(child)) return true;
+            }
+
+            if (child.object === 'block' && 'fragments' in child) {
+                for (const fragment of child.fragments) {
+                    if (traverse(fragment)) return true;
+                }
+            }
+        }
+        return false;
+    }
+
+    return traverse(document);
+}
+
 /**
  * Get the text of a block/inline.
  */

From 73e0cbb2d659a4236114cd550bbb6cc5efcb61e9 Mon Sep 17 00:00:00 2001
From: Steven H <steven@gitbook.io>
Date: Wed, 18 Jun 2025 13:26:20 +0100
Subject: [PATCH 23/23] Fix an issue where PDF export URLs were not bringing
 their query params. (#3351)

---
 .changeset/rich-buses-hunt.md                 |   5 +
 packages/gitbook-v2/src/middleware.ts         |   2 +
 packages/gitbook/e2e/pdf.spec.ts              | 170 ++++++++++++++++++
 packages/gitbook/e2e/util.ts                  |   2 +-
 packages/gitbook/package.json                 |   2 +-
 .../gitbook/src/components/PDF/PDFPage.tsx    |   2 +-
 6 files changed, 180 insertions(+), 3 deletions(-)
 create mode 100644 .changeset/rich-buses-hunt.md
 create mode 100644 packages/gitbook/e2e/pdf.spec.ts

diff --git a/.changeset/rich-buses-hunt.md b/.changeset/rich-buses-hunt.md
new file mode 100644
index 000000000..fbc59d232
--- /dev/null
+++ b/.changeset/rich-buses-hunt.md
@@ -0,0 +1,5 @@
+---
+"gitbook-v2": patch
+---
+
+Fix an issue where PDF export URLs were not keeping their query params.
diff --git a/packages/gitbook-v2/src/middleware.ts b/packages/gitbook-v2/src/middleware.ts
index d413d6a43..4bcbf77ae 100644
--- a/packages/gitbook-v2/src/middleware.ts
+++ b/packages/gitbook-v2/src/middleware.ts
@@ -259,6 +259,8 @@ async function serveSiteRoutes(requestURL: URL, request: NextRequest) {
         console.log(`rewriting ${request.nextUrl.toString()} to ${route}`);
 
         const rewrittenURL = new URL(`/${route}`, request.nextUrl.toString());
+        rewrittenURL.search = request.nextUrl.search; // Preserve the original search params
+
         const response = NextResponse.rewrite(rewrittenURL, {
             request: {
                 headers: requestHeaders,
diff --git a/packages/gitbook/e2e/pdf.spec.ts b/packages/gitbook/e2e/pdf.spec.ts
new file mode 100644
index 000000000..4798a2a04
--- /dev/null
+++ b/packages/gitbook/e2e/pdf.spec.ts
@@ -0,0 +1,170 @@
+import { argosScreenshot } from '@argos-ci/playwright';
+import { expect, test } from '@playwright/test';
+import { getContentTestURL } from '../tests/utils';
+import { waitForIcons } from './util';
+
+test.describe('PDF export', () => {
+    test('export all pages as PDF (e2e)', async ({ page }) => {
+        // Set the header to disable the Vercel toolbar
+        // But only on the main document as it'd cause CORS issues on other resources
+        await page.route('**/*', async (route, request) => {
+            if (request.resourceType() === 'document') {
+                await route.continue({
+                    headers: {
+                        ...request.headers(),
+                        'x-vercel-skip-toolbar': '1',
+                    },
+                });
+            } else {
+                await route.continue();
+            }
+        });
+
+        await page.goto(
+            getContentTestURL(
+                'https://gitbook-open-e2e-sites.gitbook.io/gitbook-doc/~gitbook/pdf?limit=10'
+            )
+        );
+
+        const printBtn = page.getByTestId('print-button');
+        await expect(printBtn).toBeVisible();
+
+        await argosScreenshot(page, 'pdf - all pages', {
+            viewports: ['macbook-13'],
+            argosCSS: `
+                            /* Hide Intercom */
+                            .intercom-lightweight-app {
+                                display: none !important;
+                            }
+                            `,
+            threshold: undefined,
+            fullPage: true,
+            beforeScreenshot: async ({ runStabilization }) => {
+                await runStabilization();
+                await waitForIcons(page);
+            },
+        });
+    });
+
+    test('export all pages as PDF (GitBook docs)', async ({ page }) => {
+        // Set the header to disable the Vercel toolbar
+        // But only on the main document as it'd cause CORS issues on other resources
+        await page.route('**/*', async (route, request) => {
+            if (request.resourceType() === 'document') {
+                await route.continue({
+                    headers: {
+                        ...request.headers(),
+                        'x-vercel-skip-toolbar': '1',
+                    },
+                });
+            } else {
+                await route.continue();
+            }
+        });
+
+        await page.goto(getContentTestURL('https://gitbook.com/docs/~gitbook/pdf?limit=10'));
+
+        const printBtn = page.getByTestId('print-button');
+        await expect(printBtn).toBeVisible();
+
+        await argosScreenshot(page, 'pdf - all pages', {
+            viewports: ['macbook-13'],
+            argosCSS: `
+                            /* Hide Intercom */
+                            .intercom-lightweight-app {
+                                display: none !important;
+                            }
+                            `,
+            threshold: undefined,
+            fullPage: true,
+            beforeScreenshot: async ({ runStabilization }) => {
+                await runStabilization();
+                await waitForIcons(page);
+            },
+        });
+    });
+
+    test('export a single page as PDF (e2e)', async ({ page }) => {
+        // Set the header to disable the Vercel toolbar
+        // But only on the main document as it'd cause CORS issues on other resources
+        await page.route('**/*', async (route, request) => {
+            if (request.resourceType() === 'document') {
+                await route.continue({
+                    headers: {
+                        ...request.headers(),
+                        'x-vercel-skip-toolbar': '1',
+                    },
+                });
+            } else {
+                await route.continue();
+            }
+        });
+
+        await page.goto(
+            getContentTestURL(
+                'https://gitbook-open-e2e-sites.gitbook.io/gitbook-doc/~gitbook/pdf?page=Bw7LjWwgTjV8nIV4s7rs&only=yes&limit=2'
+            )
+        );
+
+        const printBtn = page.getByTestId('print-button');
+        await expect(printBtn).toBeVisible();
+
+        await argosScreenshot(page, 'pdf - all pages', {
+            viewports: ['macbook-13'],
+            argosCSS: `
+                            /* Hide Intercom */
+                            .intercom-lightweight-app {
+                                display: none !important;
+                            }
+                            `,
+            threshold: undefined,
+            fullPage: true,
+            beforeScreenshot: async ({ runStabilization }) => {
+                await runStabilization();
+                await waitForIcons(page);
+            },
+        });
+    });
+
+    test('export a single page as PDF (GitBook docs)', async ({ page }) => {
+        // Set the header to disable the Vercel toolbar
+        // But only on the main document as it'd cause CORS issues on other resources
+        await page.route('**/*', async (route, request) => {
+            if (request.resourceType() === 'document') {
+                await route.continue({
+                    headers: {
+                        ...request.headers(),
+                        'x-vercel-skip-toolbar': '1',
+                    },
+                });
+            } else {
+                await route.continue();
+            }
+        });
+
+        await page.goto(
+            getContentTestURL(
+                'https://gitbook.com/docs/~gitbook/pdf?page=DfnNkU49mvLe2ythHAyx&only=yes&limit=2'
+            )
+        );
+
+        const printBtn = page.getByTestId('print-button');
+        await expect(printBtn).toBeVisible();
+
+        await argosScreenshot(page, 'pdf - all pages', {
+            viewports: ['macbook-13'],
+            argosCSS: `
+                            /* Hide Intercom */
+                            .intercom-lightweight-app {
+                                display: none !important;
+                            }
+                            `,
+            threshold: undefined,
+            fullPage: true,
+            beforeScreenshot: async ({ runStabilization }) => {
+                await runStabilization();
+                await waitForIcons(page);
+            },
+        });
+    });
+});
diff --git a/packages/gitbook/e2e/util.ts b/packages/gitbook/e2e/util.ts
index f54b70fbe..937b776d7 100644
--- a/packages/gitbook/e2e/util.ts
+++ b/packages/gitbook/e2e/util.ts
@@ -346,7 +346,7 @@ export function getCustomizationURL(partial: DeepPartial<SiteCustomizationSettin
 /**
  * Wait for all icons present on the page to be loaded.
  */
-async function waitForIcons(page: Page) {
+export async function waitForIcons(page: Page) {
     await page.waitForFunction(() => {
         const urlStates: Record<
             string,
diff --git a/packages/gitbook/package.json b/packages/gitbook/package.json
index e54901316..a430218cf 100644
--- a/packages/gitbook/package.json
+++ b/packages/gitbook/package.json
@@ -8,7 +8,7 @@
         "build:cloudflare": "next-on-pages --custom-entrypoint=./src/cloudflare-entrypoint.ts",
         "start": "next start",
         "typecheck": "tsc --noEmit",
-        "e2e": "playwright test e2e/internal.spec.ts",
+        "e2e": "playwright test e2e/internal.spec.ts e2e/pdf.spec.ts",
         "e2e-customers": "playwright test e2e/customers.spec.ts",
         "unit": "bun test {src,packages} --preload ./tests/preload-bun.ts",
         "generate": "gitbook-icons ./public/~gitbook/static/icons custom-icons && gitbook-math ./public/~gitbook/static/math",
diff --git a/packages/gitbook/src/components/PDF/PDFPage.tsx b/packages/gitbook/src/components/PDF/PDFPage.tsx
index cc9bf2807..d2bc5c91a 100644
--- a/packages/gitbook/src/components/PDF/PDFPage.tsx
+++ b/packages/gitbook/src/components/PDF/PDFPage.tsx
@@ -53,7 +53,7 @@ export async function PDFPage(props: {
 }) {
     const baseContext = props.context;
     const searchParams = new URLSearchParams(props.searchParams);
-    const pdfParams = getPDFSearchParams(new URLSearchParams(searchParams));
+    const pdfParams = getPDFSearchParams(searchParams);
 
     const customization =
         'customization' in baseContext ? baseContext.customization : defaultCustomization();
