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

Author: SamyPesse

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) {

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;

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',

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>
  );
 }

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}
  />

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: {

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;
 

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

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) : '',
+ };
+}

packages/gitbook/src/components/SiteSections/index.ts

@@ -1,2 +1,3 @@
-export * from './SiteSectionTabs';
+export * from './encodeClientSiteSections';
 export * from './SiteSectionList';
+export * from './SiteSectionTabs';