feat(theme-classic): reintroduce autoscrolling TOC

packages/docusaurus-theme-classic/src/theme/TOCItems/index.tsx

@@ -83,10 +83,17 @@ export default function TOCItems({
         linkActiveClassName,
         minHeadingLevel,
         maxHeadingLevel,
+        autoScrollTOC: themeConfig.autoScrollTOC,
       };
     }
     return undefined;
-  }, [linkClassName, linkActiveClassName, minHeadingLevel, maxHeadingLevel]);
+  }, [
+    linkClassName,
+    linkActiveClassName,
+    minHeadingLevel,
+    maxHeadingLevel,
+    themeConfig,
+  ]);
   useTOCHighlight(tocHighlightConfig);
 
   return (

packages/docusaurus-theme-classic/src/validateThemeConfig.ts

@@ -43,6 +43,7 @@ export const DEFAULT_CONFIG = {
     minHeadingLevel: 2,
     maxHeadingLevel: 3,
   },
+  autoScrollTOC: true,
 };
 
 const NavbarItemPosition = Joi.string().equal('left', 'right').default('left');
@@ -349,6 +350,7 @@ export const ThemeConfigSchema = Joi.object({
   autoCollapseSidebarCategories: Joi.bool().default(
     DEFAULT_CONFIG.autoCollapseSidebarCategories,
   ),
+  autoScrollTOC: Joi.bool().default(DEFAULT_CONFIG.autoScrollTOC),
   sidebarCollapsible: Joi.forbidden().messages({
     'any.unknown':
       'The themeConfig.sidebarCollapsible has been moved to docs plugin options. See: https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs',

packages/docusaurus-theme-common/src/hooks/useTOCHighlight.ts

@@ -127,6 +127,7 @@ export type TOCHighlightConfig = {
   minHeadingLevel: number;
   /** @see {@link TOCHighlightConfig.minHeadingLevel} */
   maxHeadingLevel: number;
+  autoScrollTOC: boolean;
 };
 
 /**
@@ -138,6 +139,8 @@ export function useTOCHighlight(config: TOCHighlightConfig | undefined): void {
 
   const anchorTopOffsetRef = useAnchorTopOffsetRef();
 
+  const cancelScroll = useRef<() => void>(() => {});
+
   useEffect(() => {
     if (!config) {
       // no-op, highlighting is disabled
@@ -149,19 +152,30 @@ export function useTOCHighlight(config: TOCHighlightConfig | undefined): void {
       linkActiveClassName,
       minHeadingLevel,
       maxHeadingLevel,
+      autoScrollTOC,
     } = config;
 
-    function updateLinkActiveClass(link: HTMLAnchorElement, active: boolean) {
-      if (active) {
-        if (lastActiveLinkRef.current && lastActiveLinkRef.current !== link) {
-          lastActiveLinkRef.current?.classList.remove(linkActiveClassName);
-        }
-        link.classList.add(linkActiveClassName);
-        lastActiveLinkRef.current = link;
-        // link.scrollIntoView({block: 'nearest'});
-      } else {
-        link.classList.remove(linkActiveClassName);
+    // When the page is scrolling (either a user scroll or smooth CSS scroll),
+    // We need to defer the TOC scroll or the two concurrent scrolls would block
+    // each other.
+    function scheduleScroll(link: HTMLAnchorElement) {
+      if (!autoScrollTOC) {
+        return () => {};
       }
+      const handle = setTimeout(() => {
+        const linkRect = link.getBoundingClientRect();
+        const viewport = window.visualViewport;
+        // Only scroll if a vertical scroll is sufficient to bring the link into
+        // view. e.g. if the window is pinch-zoomed, we should not horizontally
+        // scroll
+        if (
+          linkRect.right <= viewport.pageLeft + viewport.width &&
+          linkRect.left >= viewport.pageLeft
+        ) {
+          link.scrollIntoView({block: 'nearest', behavior: 'smooth'});
+        }
+      }, 200);
+      return () => clearTimeout(handle);
     }
 
     function updateActiveLink() {
@@ -170,12 +184,21 @@ export function useTOCHighlight(config: TOCHighlightConfig | undefined): void {
       const activeAnchor = getActiveAnchor(anchors, {
         anchorTopOffset: anchorTopOffsetRef.current,
       });
-      const activeLink = links.find(
-        (link) => activeAnchor && activeAnchor.id === getLinkAnchorValue(link),
-      );
 
       links.forEach((link) => {
-        updateLinkActiveClass(link, link === activeLink);
+        const isActive = activeAnchor?.id === getLinkAnchorValue(link);
+        if (isActive) {
+          if (lastActiveLinkRef.current !== link) {
+            lastActiveLinkRef.current?.classList.remove(linkActiveClassName);
+          }
+          link.classList.add(linkActiveClassName);
+          lastActiveLinkRef.current = link;
+          // Cancel the last scheduled TOC scroll, and start a new timeout
+          cancelScroll.current();
+          cancelScroll.current = scheduleScroll(link);
+        } else {
+          link.classList.remove(linkActiveClassName);
+        }
       });
     }
 

packages/docusaurus-theme-common/src/utils/useThemeConfig.ts

@@ -118,6 +118,7 @@ export type ThemeConfig = {
   footer?: Footer;
   hideableSidebar: boolean;
   autoCollapseSidebarCategories: boolean;
+  autoScrollTOC: boolean;
   image?: string;
   metadata: Array<{[key: string]: string}>;
   sidebarCollapsible: boolean;

website/_dogfooding/_docs tests/index.md

@@ -6,3 +6,5 @@ tags: [a, b, c, some tag]
 # Docs tests
 
 This Docusaurus docs plugin instance is meant to test fancy edge-cases that regular unit tests don't really cover.
+
+[Test link](./folder%20with%20space/doc%201.md)