From 577bf26d1e15910f8844d35827fdbc7f7694dd51 Mon Sep 17 00:00:00 2001
From: Peter White <1788320+peterwhite@users.noreply.github.com>
Date: Tue, 24 Feb 2026 09:53:36 +0100
Subject: [PATCH] Fix anchor ID collisions by removing non-content UX IDs
 (#4035)

---
 .../gitbook/src/components/AIChat/AIChatButton.tsx    |  2 +-
 .../components/Announcement/AnnouncementBanner.tsx    |  2 +-
 packages/gitbook/src/components/Footer/Footer.tsx     |  2 +-
 packages/gitbook/src/components/Header/Header.tsx     |  4 ++--
 .../gitbook/src/components/PageBody/PageCover.tsx     |  2 +-
 .../gitbook/src/components/RootLayout/globals.css     |  2 +-
 .../src/components/SiteSections/SiteSectionTabs.tsx   |  2 +-
 .../components/TableOfContents/TableOfContents.tsx    |  2 +-
 .../TableOfContents/TableOfContentsScript.tsx         |  8 ++++----
 .../gitbook/src/components/primitives/SideSheet.tsx   |  2 +-
 packages/gitbook/tailwind.config.ts                   | 11 +++++++----
 11 files changed, 21 insertions(+), 18 deletions(-)

diff --git a/packages/gitbook/src/components/AIChat/AIChatButton.tsx b/packages/gitbook/src/components/AIChat/AIChatButton.tsx
index 4c7ef06a6..77d471601 100644
--- a/packages/gitbook/src/components/AIChat/AIChatButton.tsx
+++ b/packages/gitbook/src/components/AIChat/AIChatButton.tsx
@@ -18,7 +18,7 @@ export function AIChatButton(props: {
 }) {
     const { assistant, showLabel = true, withShortcut = true } = props;
     const language = useLanguage();
-    const isMobile = useIsMobile(MOBILE_BREAKPOINT, '#header-content');
+    const isMobile = useIsMobile(MOBILE_BREAKPOINT, '[data-gb-header-content]');
 
     return (
         <Button
diff --git a/packages/gitbook/src/components/Announcement/AnnouncementBanner.tsx b/packages/gitbook/src/components/Announcement/AnnouncementBanner.tsx
index f19521a94..9112aa352 100644
--- a/packages/gitbook/src/components/Announcement/AnnouncementBanner.tsx
+++ b/packages/gitbook/src/components/Announcement/AnnouncementBanner.tsx
@@ -30,7 +30,7 @@ export function AnnouncementBanner(props: {
 
     return (
         <div
-            id="announcement-banner"
+            data-gb-announcement-banner
             className="theme-bold:bg-header-background pt-4 pb-2"
             data-nosnippet=""
         >
diff --git a/packages/gitbook/src/components/Footer/Footer.tsx b/packages/gitbook/src/components/Footer/Footer.tsx
index c6d407c3d..cd73a0063 100644
--- a/packages/gitbook/src/components/Footer/Footer.tsx
+++ b/packages/gitbook/src/components/Footer/Footer.tsx
@@ -28,7 +28,7 @@ export function Footer(props: { context: GitBookSiteContext }) {
 
     return (
         <footer
-            id="site-footer"
+            data-gb-site-footer
             className={tcls(
                 'border-tint-subtle border-t',
                 // If the footer only contains a mode toggle, we only show it on smaller screens
diff --git a/packages/gitbook/src/components/Header/Header.tsx b/packages/gitbook/src/components/Header/Header.tsx
index 78f7b8305..4d6ca1da1 100644
--- a/packages/gitbook/src/components/Header/Header.tsx
+++ b/packages/gitbook/src/components/Header/Header.tsx
@@ -35,7 +35,7 @@ export function Header(props: {
 
     return (
         <header
-            id="site-header"
+            data-gb-site-header
             className={tcls(
                 'flex',
                 'flex-col',
@@ -70,7 +70,7 @@ export function Header(props: {
             >
                 <div className="transition-all duration-300 lg:chat-open:pr-80 xl:chat-open:pr-96">
                     <div
-                        id="header-content"
+                        data-gb-header-content
                         className={tcls(
                             'gap-4',
                             'lg:gap-6',
diff --git a/packages/gitbook/src/components/PageBody/PageCover.tsx b/packages/gitbook/src/components/PageBody/PageCover.tsx
index 96dbc4993..cc31cd81f 100644
--- a/packages/gitbook/src/components/PageBody/PageCover.tsx
+++ b/packages/gitbook/src/components/PageBody/PageCover.tsx
@@ -79,7 +79,7 @@ export async function PageCover(props: {
 
     return (
         <div
-            id="page-cover"
+            data-gb-page-cover
             data-full={String(as === 'full')}
             className={tcls(
                 'overflow-hidden',
diff --git a/packages/gitbook/src/components/RootLayout/globals.css b/packages/gitbook/src/components/RootLayout/globals.css
index a0660a040..70406fd25 100644
--- a/packages/gitbook/src/components/RootLayout/globals.css
+++ b/packages/gitbook/src/components/RootLayout/globals.css
@@ -292,7 +292,7 @@ html.dark {
     color-scheme: dark light;
 }
 
-html.announcement-hidden #announcement-banner {
+html.announcement-hidden [data-gb-announcement-banner] {
     @apply hidden;
 }
 
diff --git a/packages/gitbook/src/components/SiteSections/SiteSectionTabs.tsx b/packages/gitbook/src/components/SiteSections/SiteSectionTabs.tsx
index db16546de..97b94a2ed 100644
--- a/packages/gitbook/src/components/SiteSections/SiteSectionTabs.tsx
+++ b/packages/gitbook/src/components/SiteSections/SiteSectionTabs.tsx
@@ -92,7 +92,7 @@ export function SiteSectionTabs(props: {
                         !children ? 'pr-4 sm:pr-6 md:pr-8' : 'pr-4'
                     )}
                     aria-label="Sections"
-                    id="sections"
+                    data-gb-sections
                 >
                     {structure.map((structureItem) => {
                         const { id, title, icon } = structureItem;
diff --git a/packages/gitbook/src/components/TableOfContents/TableOfContents.tsx b/packages/gitbook/src/components/TableOfContents/TableOfContents.tsx
index fb5fe1e67..e6546561b 100644
--- a/packages/gitbook/src/components/TableOfContents/TableOfContents.tsx
+++ b/packages/gitbook/src/components/TableOfContents/TableOfContents.tsx
@@ -30,7 +30,7 @@ export async function TableOfContents(props: {
             <SideSheet
                 side="left"
                 data-testid="table-of-contents"
-                id="table-of-contents"
+                data-gb-table-of-contents
                 toggleClass="navigation-open"
                 withOverlay={true}
                 withCloseButton={true}
diff --git a/packages/gitbook/src/components/TableOfContents/TableOfContentsScript.tsx b/packages/gitbook/src/components/TableOfContents/TableOfContentsScript.tsx
index f2126e091..ec5268e2c 100644
--- a/packages/gitbook/src/components/TableOfContents/TableOfContentsScript.tsx
+++ b/packages/gitbook/src/components/TableOfContents/TableOfContentsScript.tsx
@@ -12,10 +12,10 @@ export function TableOfContentsScript() {
         // Calculate and set TOC dimensions
         const updateTocLayout = () => {
             // Get key elements
-            const header = document.getElementById('site-header');
-            const banner = document.getElementById('announcement-banner');
-            const footer = document.getElementById('site-footer');
-            const pageCover = document.getElementById('page-cover');
+            const header = document.querySelector<HTMLElement>('[data-gb-site-header]');
+            const banner = document.querySelector<HTMLElement>('[data-gb-announcement-banner]');
+            const footer = document.querySelector<HTMLElement>('[data-gb-site-footer]');
+            const pageCover = document.querySelector<HTMLElement>('[data-gb-page-cover]');
 
             // Set sticky top position based on header
             const headerHeight = header?.offsetHeight ?? 0;
diff --git a/packages/gitbook/src/components/primitives/SideSheet.tsx b/packages/gitbook/src/components/primitives/SideSheet.tsx
index e4a8dcfa9..22fadda7d 100644
--- a/packages/gitbook/src/components/primitives/SideSheet.tsx
+++ b/packages/gitbook/src/components/primitives/SideSheet.tsx
@@ -245,7 +245,7 @@ export function SideSheetOverlay(props: { className?: ClassValue; onClick?: () =
     return (
         // biome-ignore lint/a11y/useKeyWithClickEvents: global escape key handler is used to close the modal sheet
         <div
-            id="side-sheet-overlay"
+            data-gb-side-sheet-overlay
             onClick={() => {
                 onClick?.();
             }}
diff --git a/packages/gitbook/tailwind.config.ts b/packages/gitbook/tailwind.config.ts
index feae7fb89..1c7de653d 100644
--- a/packages/gitbook/tailwind.config.ts
+++ b/packages/gitbook/tailwind.config.ts
@@ -600,14 +600,17 @@ const config: Config = {
             /**
              * Variant when a header is displayed.
              */
-            addVariant('site-header-none', 'body:not(:has(#site-header:not(.mobile-only))) &');
-            addVariant('site-header', 'body:has(#site-header:not(.mobile-only)) &');
+            addVariant(
+                'site-header-none',
+                'body:not(:has([data-gb-site-header]:not(.mobile-only))) &'
+            );
+            addVariant('site-header', 'body:has([data-gb-site-header]:not(.mobile-only)) &');
             addVariant('site-header-sections', [
-                'body:has(#site-header:not(.mobile-only) #sections) &',
+                'body:has([data-gb-site-header]:not(.mobile-only) [data-gb-sections]) &',
             ]);
             addVariant(
                 'announcement',
-                'html:not(.announcement-hidden):has(#announcement-banner) &'
+                'html:not(.announcement-hidden):has([data-gb-announcement-banner]) &'
             );
             addVariant('embed', 'html.embed &');