Improve linking to other sections/variants in development (#2883)

SamyPesse · web-flow · commit 270e5ef7ad5a · 2025-02-26T19:14:27.000+01:00
diff --git a/packages/gitbook-v2/src/app/utils.ts b/packages/gitbook-v2/src/app/utils.ts
@@ -94,11 +94,19 @@ function createLinkerFromParams(params: RouteLayoutParams) {
     }
 
     const gitbookURL = new URL(GITBOOK_URL);
-    return createLinker({
+    const linker = createLinker({
         protocol: gitbookURL.protocol,
         host: gitbookURL.host,
         pathname: `/url/${url.host}`,
     });
+
+    // Create link in the same format for links to other sites/sections.
+    linker.toLinkForContent = (rawURL: string) => {
+        const urlObject = new URL(rawURL);
+        return `/url/${urlObject.host}${urlObject.pathname}`;
+    };
+
+    return linker;
 }
 
 function getSiteURLFromParams(params: RouteLayoutParams) {
diff --git a/packages/gitbook-v2/src/lib/links.ts b/packages/gitbook-v2/src/lib/links.ts
@@ -23,6 +23,11 @@ export interface GitBookSpaceLinker {
      * Generate an absolute URL for a given path.
      */
     toAbsoluteURL(absolutePath: string): string;
+
+    /**
+     * Generate a link (URL or path) for a GitBook content URL (url of another site)
+     */
+    toLinkForContent(url: string): string;
 }
 
 /**
@@ -52,6 +57,10 @@ export function createLinker(
         toPathForPage({ pages, page, anchor }) {
             return linker.toPathInSpace(getPagePath(pages, page)) + (anchor ? `#${anchor}` : '');
         },
+
+        toLinkForContent(url: string): string {
+            return url;
+        },
     };
 
     return linker;
@@ -79,6 +88,10 @@ export function appendPrefixToLinker(
                 (anchor ? `#${anchor}` : '')
             );
         },
+
+        toLinkForContent(url: string): string {
+            return linker.toLinkForContent(url);
+        },
     };
 
     return linkerWithPrefix;
diff --git a/packages/gitbook/src/app/middleware/(space)/~gitbook/pdf/page.tsx b/packages/gitbook/src/app/middleware/(space)/~gitbook/pdf/page.tsx
@@ -27,9 +27,9 @@ import { tcls } from '@/lib/tailwind';
 import { type PDFSearchParams, getPDFSearchParams } from '@/lib/urls';
 import { defaultCustomizationForSpace } from '@/lib/utils';
 
-import './pdf.css';
 import { PageControlButtons } from './PageControlButtons';
 import { PrintButton } from './PrintButton';
+import './pdf.css';
 import { getV1ContextForPDF } from './pointer';
 
 const DEFAULT_LIMIT = 100;
@@ -99,7 +99,7 @@ export default async function PDFHTMLOutput(props: {
                 <div className={tcls('fixed', 'left-12', 'top-12', 'print:hidden', 'z-50')}>
                     <a
                         title={tString(language, 'pdf_goback')}
-                        href={pdfParams.back ?? context.linker.toAbsoluteURL('')}
+                        href={pdfParams.back ?? linker.toAbsoluteURL(linker.toPathInSpace(''))}
                         className={tcls(
                             'flex',
                             'flex-row',
diff --git a/packages/gitbook/src/components/Header/Header.tsx b/packages/gitbook/src/components/Header/Header.tsx
@@ -6,7 +6,7 @@ import { getSpaceLanguage, t } from '@/intl/server';
 import { tcls } from '@/lib/tailwind';
 
 import { SearchButton } from '../Search';
-import { SiteSectionTabs } from '../SiteSections';
+import { SiteSectionTabs, encodeClientSiteSections } from '../SiteSections';
 import { HeaderLink } from './HeaderLink';
 import { HeaderLinkMore } from './HeaderLinkMore';
 import { HeaderLinks } from './HeaderLinks';
@@ -95,6 +95,7 @@ export function Header(props: { context: GitBookSiteContext; withTopHeader?: boo
                         {isMultiVariants && (
                             <div className="mr-auto page-no-toc:flex hidden">
                                 <SpacesDropdown
+                                    context={context}
                                     siteSpace={siteSpace}
                                     siteSpaces={siteSpaces}
                                     className={
@@ -168,7 +169,9 @@ export function Header(props: { context: GitBookSiteContext; withTopHeader?: boo
                     </div>
                 </div>
             </div>
-            {sections ? <SiteSectionTabs sections={sections} /> : null}
+            {sections ? (
+                <SiteSectionTabs sections={encodeClientSiteSections(context, sections)} />
+            ) : null}
         </header>
     );
 }
diff --git a/packages/gitbook/src/components/Header/SpacesDropdown.tsx b/packages/gitbook/src/components/Header/SpacesDropdown.tsx
@@ -2,15 +2,18 @@ import type { SiteSpace } from '@gitbook/api';
 
 import { tcls } from '@/lib/tailwind';
 
+import type { GitBookSiteContext } from '@v2/lib/context';
 import { Dropdown, DropdownChevron, DropdownMenu } from './Dropdown';
 import { SpacesDropdownMenuItem } from './SpacesDropdownMenuItem';
 
 export function SpacesDropdown(props: {
+    context: GitBookSiteContext;
     siteSpace: SiteSpace;
     siteSpaces: SiteSpace[];
     className?: string;
 }) {
-    const { siteSpace, siteSpaces, className } = props;
+    const { context, siteSpace, siteSpaces, className } = props;
+    const { linker } = context;
 
     return (
         <Dropdown
@@ -72,7 +75,9 @@ export function SpacesDropdown(props: {
                         variantSpace={{
                             id: otherSiteSpace.id,
                             title: otherSiteSpace.title,
-                            url: otherSiteSpace.urls.published ?? otherSiteSpace.space.urls.app,
+                            url: otherSiteSpace.urls.published
+                                ? linker.toLinkForContent(otherSiteSpace.urls.published)
+                                : otherSiteSpace.space.urls.app,
                         }}
                         active={otherSiteSpace.id === siteSpace.id}
                     />
diff --git a/packages/gitbook/src/components/Header/SpacesDropdownMenuItem.tsx b/packages/gitbook/src/components/Header/SpacesDropdownMenuItem.tsx
@@ -1,18 +1,24 @@
 'use client';
 
 import type { Space } from '@gitbook/api';
-import { useSelectedLayoutSegment } from 'next/navigation';
 
+import { joinPath } from '@/lib/paths';
+import { useCurrentPagePath } from '../hooks';
 import { DropdownMenuItem } from './Dropdown';
 
 function useVariantSpaceHref(variantSpaceUrl: string) {
-    const currentPathname = useSelectedLayoutSegment() ?? '';
-    const targetUrl = new URL(variantSpaceUrl);
-    targetUrl.pathname += `/${currentPathname}`;
-    targetUrl.pathname = targetUrl.pathname.replace(/\/{2,}/g, '/').replace(/\/$/, '');
-    targetUrl.searchParams.set('fallback', 'true');
+    const currentPathname = useCurrentPagePath();
 
-    return targetUrl.toString();
+    if (URL.canParse(variantSpaceUrl)) {
+        const targetUrl = new URL(variantSpaceUrl);
+        targetUrl.pathname = joinPath(targetUrl.pathname, currentPathname);
+        targetUrl.searchParams.set('fallback', 'true');
+
+        return targetUrl.toString();
+    }
+
+    // Fallback when the URL path is a relative path (in development mode)
+    return `${joinPath(variantSpaceUrl, currentPathname)}?fallback=true`;
 }
 
 export function SpacesDropdownMenuItem(props: {
diff --git a/packages/gitbook/src/components/SiteSections/SiteSectionList.tsx b/packages/gitbook/src/components/SiteSections/SiteSectionList.tsx
@@ -1,24 +1,27 @@
 'use client';
 
-import type { SiteSection, SiteSectionGroup } from '@gitbook/api';
 import { Icon, type IconName } from '@gitbook/icons';
 import { motion } from 'framer-motion';
 import React from 'react';
 
-import type { SectionsList } from '@/lib/api';
 import { type ClassValue, tcls } from '@/lib/tailwind';
 
 import { TOCScrollContainer, useScrollToActiveTOCItem } from '../TableOfContents/TOCScroller';
 import { useIsMounted, useToggleAnimation } from '../hooks';
 import { Link } from '../primitives';
 import { SectionIcon } from './SectionIcon';
+import type {
+    ClientSiteSection,
+    ClientSiteSectionGroup,
+    ClientSiteSections,
+} from './encodeClientSiteSections';
 
 const MAX_ITEMS = 5; // If there are more sections than this, they'll be shown below the fold in a scrollview.
 
 /**
  * A list of items representing site sections for multi-section sites
  */
-export function SiteSectionList(props: { sections: SectionsList; className: ClassValue }) {
+export function SiteSectionList(props: { sections: ClientSiteSections; className: ClassValue }) {
     const {
         sections: { list: sectionsAndGroups, current: currentSection },
         className,
@@ -63,7 +66,7 @@ export function SiteSectionList(props: { sections: SectionsList; className: Clas
 }
 
 export function SiteSectionListItem(props: {
-    section: SiteSection;
+    section: ClientSiteSection;
     isActive: boolean;
     className?: string;
 }) {
@@ -77,7 +80,7 @@ export function SiteSectionListItem(props: {
 
     return (
         <Link
-            href={section.urls.published ?? ''}
+            href={section.url}
             ref={linkRef}
             aria-current={isActive && 'page'}
             className={tcls(
@@ -111,8 +114,8 @@ export function SiteSectionListItem(props: {
 }
 
 export function SiteSectionGroupItem(props: {
-    group: SiteSectionGroup;
-    currentSection: SiteSection;
+    group: ClientSiteSectionGroup;
+    currentSection: ClientSiteSection;
 }) {
     const { group, currentSection } = props;
 
diff --git a/packages/gitbook/src/components/SiteSections/SiteSectionTabs.tsx b/packages/gitbook/src/components/SiteSections/SiteSectionTabs.tsx
@@ -1,22 +1,21 @@
 'use client';
 
-import type { SiteSection } from '@gitbook/api';
 import { Icon, type IconName } from '@gitbook/icons';
 import * as NavigationMenu from '@radix-ui/react-navigation-menu';
 import React from 'react';
 
 import { Link } from '@/components/primitives';
-import type { SectionsList } from '@/lib/api';
 import { tcls } from '@/lib/tailwind';
 
 import { SectionIcon } from './SectionIcon';
+import type { ClientSiteSection, ClientSiteSections } from './encodeClientSiteSections';
 
 const VIEWPORT_ITEM_WIDTH = 240; /* width of the tile (w-60) */
 const MIN_ITEMS_FOR_COLS = 4; /* number of items to switch to 2 columns */
 /**
  * A set of navigational links representing site sections for multi-section sites
  */
-export function SiteSectionTabs(props: { sections: SectionsList }) {
+export function SiteSectionTabs(props: { sections: ClientSiteSections }) {
     const {
         sections: { list: sectionsAndGroups, current: currentSection },
     } = props;
@@ -91,9 +90,7 @@ export function SiteSectionTabs(props: { sections: SectionsList }) {
                                             </NavigationMenu.Trigger>
                                             <NavigationMenu.Content className="absolute top-0 left-0 z-20 w-full data-[motion=from-end]:motion-safe:animate-enterFromRight data-[motion=from-start]:motion-safe:animate-enterFromLeft data-[motion=to-end]:motion-safe:animate-exitToRight data-[motion=to-start]:motion-safe:animate-exitToLeft md:w-max">
                                                 <SectionGroupTileList
-                                                    sections={
-                                                        sectionOrGroup.sections as SiteSection[]
-                                                    }
+                                                    sections={sectionOrGroup.sections}
                                                     currentSection={currentSection}
                                                 />
                                             </NavigationMenu.Content>
@@ -102,7 +99,7 @@ export function SiteSectionTabs(props: { sections: SectionsList }) {
                                 ) : (
                                     <NavigationMenu.Link asChild>
                                         <SectionTab
-                                            url={sectionOrGroup.urls.published ?? ''}
+                                            url={sectionOrGroup.url}
                                             isActive={isActive}
                                             title={title}
                                             icon={icon ? (icon as IconName) : undefined}
@@ -213,7 +210,10 @@ function ActiveTabIndicator() {
 /**
  * A list of section tiles grouped in the dropdown for a section group
  */
-function SectionGroupTileList(props: { sections: SiteSection[]; currentSection: SiteSection }) {
+function SectionGroupTileList(props: {
+    sections: ClientSiteSection[];
+    currentSection: ClientSiteSection;
+}) {
     const { sections, currentSection } = props;
     return (
         <ul
@@ -236,13 +236,13 @@ function SectionGroupTileList(props: { sections: SiteSection[]; currentSection:
 /**
  * A section tile shown in the dropdown for a section group
  */
-function SectionGroupTile(props: { section: SiteSection; isActive: boolean }) {
+function SectionGroupTile(props: { section: ClientSiteSection; isActive: boolean }) {
     const { section, isActive } = props;
-    const { urls, icon, title } = section;
+    const { url, icon, title } = section;
     return (
         <li className="flex w-full md:w-60">
             <Link
-                href={urls.published ?? ''}
+                href={url}
                 className={tcls(
                     'flex min-h-12 w-full select-none flex-col gap-2 rounded p-3 transition-colors hover:bg-tint-hover',
                     isActive
diff --git a/packages/gitbook/src/components/SiteSections/encodeClientSiteSections.ts b/packages/gitbook/src/components/SiteSections/encodeClientSiteSections.ts
@@ -0,0 +1,58 @@
+import type { SiteSection, SiteSectionGroup } from '@gitbook/api';
+import type { GitBookSiteContext, SiteSections } from '@v2/lib/context';
+
+export type ClientSiteSections = {
+    list: (ClientSiteSection | ClientSiteSectionGroup)[];
+    current: ClientSiteSection;
+};
+
+export type ClientSiteSection = Pick<
+    SiteSection,
+    'id' | 'title' | 'description' | 'icon' | 'object'
+> & {
+    url: string;
+};
+
+export type ClientSiteSectionGroup = Pick<SiteSectionGroup, 'id' | 'title' | 'icon' | 'object'> & {
+    sections: ClientSiteSection[];
+};
+
+/**
+ * Encode the list of site sections into the data to be rendered in the client.
+ */
+export function encodeClientSiteSections(context: GitBookSiteContext, sections: SiteSections) {
+    const { list, current } = 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.map((section) => encodeSection(context, section)),
+            });
+        } else {
+            clientSections.push(encodeSection(context, item));
+        }
+    }
+
+    return {
+        list: clientSections,
+        current: encodeSection(context, current),
+    };
+}
+
+function encodeSection(context: GitBookSiteContext, section: SiteSection) {
+    const { linker } = context;
+    return {
+        id: section.id,
+        title: section.title,
+        description: section.description,
+        icon: section.icon,
+        object: section.object,
+        url: section.urls.published ? linker.toLinkForContent(section.urls.published) : '',
+    };
+}
diff --git a/packages/gitbook/src/components/SiteSections/index.ts b/packages/gitbook/src/components/SiteSections/index.ts
@@ -1,2 +1,3 @@
-export * from './SiteSectionTabs';
+export * from './encodeClientSiteSections';
 export * from './SiteSectionList';
+export * from './SiteSectionTabs';
diff --git a/packages/gitbook/src/components/SpaceLayout/SpaceLayout.tsx b/packages/gitbook/src/components/SpaceLayout/SpaceLayout.tsx
@@ -14,7 +14,7 @@ import { getSitePointerFromContext } from '@/lib/v1';
 
 import { SpacesDropdown } from '../Header/SpacesDropdown';
 import { InsightsProvider } from '../Insights';
-import { SiteSectionList } from '../SiteSections';
+import { SiteSectionList, encodeClientSiteSections } from '../SiteSections';
 
 /**
  * Render the entire layout of the space (header, table of contents, footer).
@@ -108,11 +108,12 @@ export function SpaceLayout(props: {
                             {!withTopHeader && withSections && sections && (
                                 <SiteSectionList
                                     className={tcls('hidden', 'lg:block')}
-                                    sections={sections}
+                                    sections={encodeClientSiteSections(context, sections)}
                                 />
                             )}
                             {isMultiVariants && (
                                 <SpacesDropdown
+                                    context={context}
                                     siteSpace={siteSpace}
                                     siteSpaces={siteSpaces}
                                     className={tcls('w-full')}
diff --git a/packages/gitbook/src/lib/api.ts b/packages/gitbook/src/lib/api.ts
