From a550bcc328fb6e103677d098f188871541c6d82a Mon Sep 17 00:00:00 2001
From: Zeno Kapitein <zeno@gitbook.io>
Date: Mon, 17 Nov 2025 17:18:15 +0100
Subject: [PATCH 1/2] Optimise page outline

Removing `AsideSectionHighlight` in favour of CSS-only changes on the active link element itself prevents a repaint and reduces lag (especially on Safari).
---
 .../src/components/PageAside/PageAside.tsx    |  6 +++-
 .../PageAside/ScrollSectionsList.tsx          | 32 +++++++------------
 2 files changed, 16 insertions(+), 22 deletions(-)

diff --git a/packages/gitbook/src/components/PageAside/PageAside.tsx b/packages/gitbook/src/components/PageAside/PageAside.tsx
index 5bf96aeaf4..8874c6ba0a 100644
--- a/packages/gitbook/src/components/PageAside/PageAside.tsx
+++ b/packages/gitbook/src/components/PageAside/PageAside.tsx
@@ -169,7 +169,11 @@ async function PageAsideSections(props: { document: JSONDocument; context: GitBo
 
     const sections = await getDocumentSections(context, document);
 
-    return sections.length > 1 ? <ScrollSectionsList sections={sections} /> : null;
+    return sections.length > 1 ? (
+        <div className="overflow-y-auto">
+            <ScrollSectionsList sections={sections} />
+        </div>
+    ) : null;
 }
 
 function PageAsideActions(props: {
diff --git a/packages/gitbook/src/components/PageAside/ScrollSectionsList.tsx b/packages/gitbook/src/components/PageAside/ScrollSectionsList.tsx
index 37c24ba6f2..0fb2bb263e 100644
--- a/packages/gitbook/src/components/PageAside/ScrollSectionsList.tsx
+++ b/packages/gitbook/src/components/PageAside/ScrollSectionsList.tsx
@@ -7,7 +7,6 @@ import { tcls } from '@/lib/tailwind';
 
 import { useBodyLoaded } from '@/components/primitives';
 import { HEADER_HEIGHT_DESKTOP } from '../layout';
-import { AsideSectionHighlight } from './AsideSectionHighlight';
 
 /**
  * The threshold at which we consider a section as intersecting the viewport.
@@ -44,7 +43,7 @@ export function ScrollSectionsList({ sections }: { sections: DocumentSection[] }
 
     return (
         <ul
-            className="relative flex flex-col overflow-y-auto border-tint-subtle sidebar-list-line:border-l pb-5 xl:max-2xl:page-api-block:mt-0 xl:max-2xl:page-api-block:p-2"
+            className="relative flex flex-col border-tint-subtle sidebar-list-line:border-l pb-5 xl:max-2xl:page-api-block:mt-0 xl:max-2xl:page-api-block:p-2"
             ref={scrollContainerRef}
         >
             {sections.map((section) => (
@@ -62,22 +61,6 @@ export function ScrollSectionsList({ sections }: { sections: DocumentSection[] }
                     )}
                     ref={activeId === section.id ? activeItemRef : null}
                 >
-                    {activeId === section.id && (
-                        <AsideSectionHighlight
-                            className={tcls(
-                                'sidebar-list-default:hidden',
-                                section?.depth > 1
-                                    ? [
-                                          'sidebar-list-default:rounded-l-none',
-                                          'sidebar-list-line:rounded-l-none',
-                                      ]
-                                    : [
-                                          'sidebar-list-default:ml-3',
-                                          'contrast-more:sidebar-list-default:ml-0',
-                                      ]
-                            )}
-                        />
-                    )}
                     <a
                         href={`#${section.id}`}
                         className={tcls(
@@ -104,6 +87,10 @@ export function ScrollSectionsList({ sections }: { sections: DocumentSection[] }
                             'contrast-more:hover:ring-inset',
                             'contrast-more:hover:ring-current',
 
+                            'sidebar-list-line:border-l-2',
+                            'border-transparent',
+                            'sidebar-list-line:-left-px',
+
                             section.depth > 1 && [
                                 'subitem',
                                 'sidebar-list-line:pl-6',
@@ -120,17 +107,20 @@ export function ScrollSectionsList({ sections }: { sections: DocumentSection[] }
                                 'hover:text-primary',
                                 'contrast-more:text-primary',
                                 'contrast-more:hover:text-primary-strong',
-                                'sidebar-list-line:ml-px',
-
                                 'hover:bg-primary-hover',
+
                                 'theme-muted:hover:bg-primary-active',
                                 '[html.sidebar-filled.theme-bold.tint_&]:hover:bg-primary-active',
                                 'theme-gradient:hover:bg-primary-active',
-
                                 'tint:font-semibold',
                                 'contrast-more:font-semibold',
 
+                                'sidebar-list-line:border-primary-9',
                                 'sidebar-list-default:border-tint',
+
+                                'sidebar-list-pill:bg-primary',
+                                '[html.theme-muted.sidebar-list-pill_&]:bg-primary-hover',
+                                '[html.theme-gradient.sidebar-list-pill_&]:bg-primary-active',
                             ]
                         )}
                     >

From 5de404559371ae42daae63d23466cbfe7b327398 Mon Sep 17 00:00:00 2001
From: Zeno Kapitein <zeno@gitbook.io>
Date: Mon, 17 Nov 2025 17:20:25 +0100
Subject: [PATCH 2/2] Delete AsideSectionHighlight.tsx

---
 .../PageAside/AsideSectionHighlight.tsx       | 41 -------------------
 1 file changed, 41 deletions(-)
 delete mode 100644 packages/gitbook/src/components/PageAside/AsideSectionHighlight.tsx

diff --git a/packages/gitbook/src/components/PageAside/AsideSectionHighlight.tsx b/packages/gitbook/src/components/PageAside/AsideSectionHighlight.tsx
deleted file mode 100644
index 9fb0186cd1..0000000000
--- a/packages/gitbook/src/components/PageAside/AsideSectionHighlight.tsx
+++ /dev/null
@@ -1,41 +0,0 @@
-'use client';
-
-import { type ClassValue, tcls } from '@/lib/tailwind';
-import React from 'react';
-
-export const AsideSectionHighlight = React.memo(
-    ({
-        className,
-    }: {
-        className?: ClassValue;
-    }) => {
-        return (
-            <div
-                className={tcls([
-                    'border-primary-9',
-                    'tint:border-primary-11',
-                    'sidebar-list-line:border-l-2',
-
-                    'inset-0',
-                    'pointer-events-none',
-                    'absolute',
-                    'z-0',
-                    'sidebar-list-line:-left-px',
-
-                    'rounded-md',
-                    'straight-corners:rounded-none',
-                    'circular-corners:rounded-2xl',
-                    'sidebar-list-line:rounded-l-none!',
-
-                    'sidebar-list-pill:bg-primary',
-                    '[html.theme-muted.sidebar-list-pill_&]:bg-primary-hover',
-                    '[html.theme-gradient.sidebar-list-pill_&]:bg-primary-active',
-
-                    'contrast-more:border',
-                    'contrast-more:bg-primary',
-                    className,
-                ])}
-            />
-        );
-    }
-);