From 6ca9e88a4dee17f3904713b9f991588d8742e614 Mon Sep 17 00:00:00 2001
From: taranvohra <taranvohra@outlook.com>
Date: Thu, 30 Oct 2025 11:36:39 +0530
Subject: [PATCH 1/3] Compute the correct canonical and alternate tags

---
 .../src/components/SitePage/SitePage.tsx      | 57 +++++++++++++++++--
 1 file changed, 52 insertions(+), 5 deletions(-)

diff --git a/packages/gitbook/src/components/SitePage/SitePage.tsx b/packages/gitbook/src/components/SitePage/SitePage.tsx
index 29bb504a41..322aeb4e65 100644
--- a/packages/gitbook/src/components/SitePage/SitePage.tsx
+++ b/packages/gitbook/src/components/SitePage/SitePage.tsx
@@ -3,6 +3,7 @@ import { getPageDocument } from '@/lib/data';
 import {
     CustomizationHeaderPreset,
     CustomizationThemeMode,
+    type RevisionPageDocument,
     SiteInsightsDisplayContext,
 } from '@gitbook/api';
 import type { Metadata, Viewport } from 'next';
@@ -14,7 +15,9 @@ import { getPagePath } from '@/lib/pages';
 import { isPageIndexable, isSiteIndexable } from '@/lib/seo';
 
 import { getResizedImageURL } from '@/lib/images';
+import { removeTrailingSlash } from '@/lib/paths';
 import { tcls } from '@/lib/tailwind';
+import { assert } from 'ts-essentials';
 import { PageContextProvider } from '../PageContext';
 import { PageClientLayout } from './PageClientLayout';
 import { type PagePathParams, fetchPageData, getPathnameParam } from './fetch';
@@ -106,16 +109,15 @@ export async function generateSitePageMetadata(props: SitePageProps): Promise<Me
     }
 
     const { page, ancestors } = pageTarget;
-    const { site, customization, revision, linker, imageResizer } = context;
+    const { site, customization, linker, imageResizer } = context;
+    const { canonical, languages } = getCanonicalAndLanguages(context, page);
 
     return {
         title: [page.title, site.title].filter(Boolean).join(' | '),
         description: page.description ?? '',
         alternates: {
-            // Trim trailing slashes in canonical URL to match the redirect behavior
-            canonical: linker
-                .toAbsoluteURL(linker.toPathForPage({ pages: revision.pages, page }))
-                .replace(/\/+$/, ''),
+            canonical,
+            languages,
             types: {
                 'text/markdown': `${linker.toAbsoluteURL(linker.toPathInSpace(page.path))}.md`,
             },
@@ -137,6 +139,51 @@ export async function generateSitePageMetadata(props: SitePageProps): Promise<Me
     };
 }
 
+function getCanonicalAndLanguages(context: GitBookSiteContext, page: RevisionPageDocument) {
+    const { siteSpaces, siteSpace, revision } = context;
+
+    const linker =
+        siteSpace.default || typeof siteSpace.space.language !== 'undefined'
+            ? context.linker
+            : context.linker.fork({
+                  spaceBasePath: removeTrailingSlash(
+                      context.linker.spaceBasePath.split('/').filter(Boolean).slice(0, -1).join('/')
+                  ),
+              });
+
+    // Trim trailing slashes in canonical URL to match the redirect behavior
+    const canonical = linker
+        .toAbsoluteURL(linker.toPathForPage({ pages: revision.pages, page }))
+        .replace(/\/+$/, '');
+
+    // Get other language versions
+    const languages: NonNullable<Metadata['alternates']>['languages'] = {};
+    siteSpaces
+        .filter(
+            (sp) => sp.section === siteSpace.section && typeof sp.space.language !== 'undefined'
+        )
+        .forEach((langSiteSpace) => {
+            const publishedURL = langSiteSpace.urls.published;
+            const language = langSiteSpace.space.language;
+            assert(publishedURL, `Published URL must be defined for space in ${langSiteSpace.id}`);
+            assert(language, `Language must be defined for space in ${langSiteSpace.id}`);
+
+            const langSiteSpaceURL = linker.toAbsoluteURL(
+                linker.toLinkForContent(new URL(publishedURL).toString())
+            );
+
+            // @ts-expect-error
+            languages[language] = new URL(
+                getPagePath(revision.pages, page),
+                langSiteSpaceURL.endsWith('/') ? langSiteSpaceURL : `${langSiteSpaceURL}/`
+            )
+                .toString()
+                .replace(/\/+$/, '');
+        });
+
+    return { canonical, languages };
+}
+
 /**
  * Fetches all the data required to render the site page.
  */

From b78159541d512f02483605940674ba12ea19935f Mon Sep 17 00:00:00 2001
From: taranvohra <taranvohra@outlook.com>
Date: Thu, 30 Oct 2025 11:40:39 +0530
Subject: [PATCH 2/3] comment

---
 packages/gitbook/src/components/SitePage/SitePage.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/gitbook/src/components/SitePage/SitePage.tsx b/packages/gitbook/src/components/SitePage/SitePage.tsx
index 322aeb4e65..cacb810f00 100644
--- a/packages/gitbook/src/components/SitePage/SitePage.tsx
+++ b/packages/gitbook/src/components/SitePage/SitePage.tsx
@@ -172,7 +172,7 @@ function getCanonicalAndLanguages(context: GitBookSiteContext, page: RevisionPag
                 linker.toLinkForContent(new URL(publishedURL).toString())
             );
 
-            // @ts-expect-error
+            // @ts-expect-error - Metadata.languages does not have all the language types that GitBook supports
             languages[language] = new URL(
                 getPagePath(revision.pages, page),
                 langSiteSpaceURL.endsWith('/') ? langSiteSpaceURL : `${langSiteSpaceURL}/`

From f61a29d4f3fab961ecc5b9cca49977ca03cd5bed Mon Sep 17 00:00:00 2001
From: taranvohra <taranvohra@outlook.com>
Date: Fri, 31 Oct 2025 12:00:05 +0530
Subject: [PATCH 3/3] add comment

---
 .../src/components/SitePage/SitePage.tsx        | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/packages/gitbook/src/components/SitePage/SitePage.tsx b/packages/gitbook/src/components/SitePage/SitePage.tsx
index cacb810f00..85a89235dd 100644
--- a/packages/gitbook/src/components/SitePage/SitePage.tsx
+++ b/packages/gitbook/src/components/SitePage/SitePage.tsx
@@ -139,6 +139,9 @@ export async function generateSitePageMetadata(props: SitePageProps): Promise<Me
     };
 }
 
+/**
+ * Generates the canonical URL and alternate language URLs for the given page.
+ */
 function getCanonicalAndLanguages(context: GitBookSiteContext, page: RevisionPageDocument) {
     const { siteSpaces, siteSpace, revision } = context;
 
@@ -152,10 +155,18 @@ function getCanonicalAndLanguages(context: GitBookSiteContext, page: RevisionPag
               });
 
     // Trim trailing slashes in canonical URL to match the redirect behavior
-    const canonical = linker
-        .toAbsoluteURL(linker.toPathForPage({ pages: revision.pages, page }))
-        .replace(/\/+$/, '');
+    const canonicalURL = new URL(
+        linker
+            .toAbsoluteURL(linker.toPathForPage({ pages: revision.pages, page }))
+            .replace(/\/+$/, '')
+    );
+
+    // For non-default site spaces, add a fallback query param so a page not found can still redirect to the home page
+    if (!siteSpace.default) {
+        canonicalURL.searchParams.set('fallback', 'true');
+    }
 
+    const canonical = canonicalURL.toString();
     // Get other language versions
     const languages: NonNullable<Metadata['alternates']>['languages'] = {};
     siteSpaces