Fix anchor URL resolution (#4249)

Author: clairechabas

packages/gitbook/src/components/hooks/useHash.tsx

@@ -68,7 +68,7 @@ export const NavigationStatusProvider: React.FC<React.PropsWithChildren> = ({ ch
         }
         const url = new URL(
             href,
-            typeof window !== 'undefined' ? window.location.origin : 'http://localhost'
+            typeof window !== 'undefined' ? window.location.href : 'http://localhost'
         );
         setHash(url.hash.slice(1));
 

packages/gitbook/src/components/primitives/Link.tsx

@@ -4,6 +4,7 @@ import NextLink, { type LinkProps as NextLinkProps } from 'next/link';
 import React from 'react';
 
 import { tcls } from '@/lib/tailwind';
+import { checkIsAnchor, resolveAnchorURL } from '@/lib/urls';
 import { type TrackEventInput, useTrackEvent } from '../Insights';
 import { NavigationStatusContext } from '../hooks';
 import { isExternalLink, toNonEmbedLink } from '../utils/link';
@@ -88,12 +89,20 @@ export function Link(props: LinkProps) {
     const trackEvent = useTrackEvent();
     const forwardedClassNames = useClassnames(classNames || []);
     const isExternal = isExternalServer(href);
+    const isAnchor = checkIsAnchor(href);
     const { target, rel } = getTargetProps(props, { externalTarget, isExternal });
 
     const onClick = (event: React.MouseEvent<HTMLAnchorElement>) => {
         // Only trigger navigation context for internal links in the same window without modifier keys (i.e. open in new tab).
         if (!isExternal && target !== '_blank' && !event.ctrlKey && !event.metaKey) {
-            onNavigationClick(href);
+            if (isAnchor) {
+                event.preventDefault();
+                const resolvedHref = resolveAnchorURL(href, window.location);
+                window.history.pushState(null, '', resolvedHref);
+                onNavigationClick(resolvedHref);
+            } else {
+                onNavigationClick(href);
+            }
         }
 
         const isExternalOnClient = isExternalClient(href);

packages/gitbook/src/lib/urls.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'bun:test';
+
+import { resolveAnchorURL } from './urls';
+
+describe('resolveAnchorURL', () => {
+    it('replaces the current location hash with the new anchor', () => {
+        expect(
+            resolveAnchorURL('#new-anchor', {
+                href: 'https://gitbook.com/docs/creating-content/blocks/heading#anchor-links',
+            })
+        ).toBe('/docs/creating-content/blocks/heading#new-anchor');
+    });
+
+    it('preserves URL path and search params when replacing the hash', () => {
+        expect(
+            resolveAnchorURL('#new-anchor', {
+                href: 'https://gitbook.com/docs/creating-content/blocks/heading?fallback=true&query=%74est#anchor-links',
+            })
+        ).toBe('/docs/creating-content/blocks/heading?fallback=true&query=%74est#new-anchor');
+    });
+});

packages/gitbook/src/lib/urls.ts

@@ -22,3 +22,12 @@ export function checkIsExternalURL(input: string): boolean {
 export function checkIsAnchor(input: string): boolean {
     return input.startsWith('#');
 }
+
+/**
+ * Resolve a hash-only anchor against a location while replacing any existing hash.
+ */
+export function resolveAnchorURL(anchor: string, location: Pick<Location, 'href'>): string {
+    const url = new URL(location.href);
+    url.hash = anchor;
+    return `${url.pathname}${url.search}${url.hash}`;
+}