From 111bad9d2afc2a1fb6d8b1caafb9b9eb8161c901 Mon Sep 17 00:00:00 2001
From: Zeno Kapitein <zeno@gitbook.io>
Date: Tue, 18 Aug 2026 14:05:39 +0200
Subject: [PATCH 1/2] Fix: highlight TOC link entry when on the page or section
 it points to

A table-of-contents entry of type "link" that resolves to a page in the
current space now computes its active state the same way page entries do,
comparing the target page's paths against the current page path.

Links pointing to a section of a page also highlight, but only while the
reader is at that section, so sibling links to other sections of the same
page don't all light up together. Cross-space and external targets are
still excluded.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../TableOfContents/PageLinkItem.tsx          | 16 ++++++++++++++-
 .../encodeClientTableOfContents.ts            | 20 +++++++++++++++++++
 2 files changed, 35 insertions(+), 1 deletion(-)

diff --git a/packages/gitbook/src/components/TableOfContents/PageLinkItem.tsx b/packages/gitbook/src/components/TableOfContents/PageLinkItem.tsx
index 43048c73e8..7c5dbb7a08 100644
--- a/packages/gitbook/src/components/TableOfContents/PageLinkItem.tsx
+++ b/packages/gitbook/src/components/TableOfContents/PageLinkItem.tsx
@@ -3,6 +3,7 @@
 import { SiteInsightsLinkPosition } from '@gitbook/api';
 import { Icon } from '@gitbook/icons';
 
+import { useCurrentPagePath, useHash } from '../hooks';
 import type { ClientTOCPageLink } from './encodeClientTableOfContents';
 import { TOCPageIcon } from './TOCPageIcon';
 import { Link } from '@/components/primitives';
@@ -13,11 +14,24 @@ export function PageLinkItem(props: { page: ClientTOCPageLink }) {
 
     const isExternal = page.target.kind === 'url';
 
+    const currentPagePath = useCurrentPagePath();
+    const hash = useHash();
+    const isOnTargetPage =
+        page.pathnames?.some((pathname) => pathname === currentPagePath) ?? false;
+    // A link to a section only lights up once the reader is at that section, so sibling links
+    // pointing at other sections of the same page don't all highlight together.
+    const isActive = isOnTargetPage && (!page.anchor || page.anchor === hash);
+
     return (
         <li className="page-link-item flex flex-col [.page-group-item+&]:mt-4">
             <Link
                 href={page.href ?? '#'}
-                classNames={['ToCLinkItemStyles']}
+                data-active={isActive}
+                aria-current={isActive ? 'page' : undefined}
+                classNames={[
+                    'ToCLinkItemStyles',
+                    ...(isActive ? ['ToCLinkItemActiveStyles' as const] : []),
+                ]}
                 insights={{
                     type: 'link_click',
                     link: {
diff --git a/packages/gitbook/src/components/TableOfContents/encodeClientTableOfContents.ts b/packages/gitbook/src/components/TableOfContents/encodeClientTableOfContents.ts
index 3233b032ee..a10ec1098a 100644
--- a/packages/gitbook/src/components/TableOfContents/encodeClientTableOfContents.ts
+++ b/packages/gitbook/src/components/TableOfContents/encodeClientTableOfContents.ts
@@ -18,6 +18,10 @@ export type ClientTOCPageLink = {
     emoji?: string;
     icon?: string;
     target: ContentRef;
+    /** Paths of the page this link points to, when it resolves to a page in the current space. */
+    pathnames?: string[];
+    /** Anchor the link points to on that page, when the target is a section of it. */
+    anchor?: string;
 };
 
 export type ClientTOCPageDocument = {
@@ -96,6 +100,15 @@ export async function encodeClientTableOfContents(
             }
             case 'link': {
                 const resolved = await resolveContentRef(page.target, context);
+                // Links to a page (or a section of one) in the current space compute their active
+                // state the same way page entries do. Cross-space and external targets are left out
+                // to avoid over-highlighting.
+                const targetPage =
+                    (page.target.kind === 'page' || page.target.kind === 'anchor') &&
+                    resolved?.page &&
+                    resolved.space?.id === context.space.id
+                        ? resolved.page
+                        : undefined;
                 result.push(
                     removeUndefined({
                         id: page.id,
@@ -104,6 +117,13 @@ export async function encodeClientTableOfContents(
                         emoji: page.emoji,
                         icon: page.icon,
                         target: page.target,
+                        pathnames: targetPage
+                            ? getSiteSpacePagePaths(context.siteSpace, rootPages, targetPage)
+                            : undefined,
+                        anchor:
+                            targetPage && page.target.kind === 'anchor'
+                                ? page.target.anchor
+                                : undefined,
                         type: 'link',
                     })
                 );

From 5b4f17bff4e683f322b6212aca7477c25267580f Mon Sep 17 00:00:00 2001
From: Zeno Kapitein <zeno@gitbook.io>
Date: Tue, 18 Aug 2026 14:05:39 +0200
Subject: [PATCH 2/2] changeset

---
 .changeset/toc-link-active-highlight.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/toc-link-active-highlight.md

diff --git a/.changeset/toc-link-active-highlight.md b/.changeset/toc-link-active-highlight.md
new file mode 100644
index 0000000000..2eb6266140
--- /dev/null
+++ b/.changeset/toc-link-active-highlight.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Highlight a table-of-contents link entry as active when it points to the page — or the section of a page — you are currently viewing.