fix: ensure ScrollSpy can always find the TOC

docsy.dev/hugo.yaml

@@ -106,7 +106,7 @@ params:
         icon: fa-brands fa-github
         desc: Discussion and help from your fellow users
       - name: User mailing list
-        url: https://groups.google.com/forum/#!forum/docsy-users
+        url: https://groups.google.com/g/docsy-users
         icon: fa-solid fa-envelope
         desc: Sign up for Docsy announcements
       - name: Twitter

docsy.dev/static/refcache.json

@@ -2059,9 +2059,9 @@
     "StatusCode": 200,
     "LastSeen": "2025-05-16T09:20:44.343705-04:00"
   },
-  "https://groups.google.com/forum/#!forum/docsy-users": {
+  "https://groups.google.com/g/docsy-users": {
     "StatusCode": 200,
-    "LastSeen": "2025-10-06T11:53:59.999Z"
+    "LastSeen": "2025-11-16T11:42:02.524144-05:00"
   },
   "https://help.github.com/articles/about-pull-requests/": {
     "StatusCode": 206,

layouts/_partials/td/scrollspy-attr.txt

@@ -1,10 +1,23 @@
+{{/*
+
+Ensure that the value of `data-bs-target` is a selector to an element that will
+always exist, otherwise ScrollSpy will scan the full page body, and this can
+cause problems -- see
+https://github.com/google/docsy/issues/2328#issuecomment-3538869206.
+
+`data-scrollspy-attr-cache-base` is only a diagnostic.
+
+*/ -}}
+
 {{ if not (.Param "ui.scrollSpy.disable") -}}
   {{ $rootMargin := .Param "ui.scrollSpy.rootMargin" | default "0px 0px -10%" -}}
   {{/* Note that we tried `data-bs-smooth-scroll="true"`, but it breaks browser URL updates.
        For details, see https://github.com/google/docsy/pull/2291 */ -}}
   {{ $attr := slice
       ` data-bs-spy="scroll"`
-      ` data-bs-target="#TableOfContents"`
-      (printf ` data-bs-root-margin="%s"` $rootMargin) -}}
+      ` data-bs-target=".td-toc"`
+      (printf ` data-bs-root-margin="%s"` $rootMargin)
+      (printf ` data-scrollspy-attr-cache-base="%s"` .Path)
+  -}}
   {{ delimit $attr "" -}}
 {{ end -}}

layouts/_partials/toc.html

@@ -1,41 +1,39 @@
 {{/*
 
-  FIXME: This is a temporary hack to adjust the heading IDs until Bootstrap fixes
-  ScrollSpy. For details, see:
+  FIXME: The $safeIds functionality is a temporary workaround for the ScrollSpy
+  bug described in https://github.com/google/docsy/issues/2329. For details,
+  also see https://www.docsy.dev/blog/2025/0.13.0.
 
-  - https://www.docsy.dev/blog/2025/0.13.0
-  - https://github.com/google/docsy/issues/2329
+  Always render the dev.td-toc element. ScrollSpy is counting on it to exist,
+  even if it's empty.
 
   cSpell:ignore notoc
 */ -}}
 
-{{ $scrollSpyEnabled := not (.Param "ui.scrollSpy.disable") -}}
-{{ $safeIds := .Param "ui.scrollSpy.safeIds" | default $scrollSpyEnabled -}}
-
+<div class="td-toc" data-proofer-ignore data-log="hi">
 {{ if not .Params.notoc -}}
-  {{ $page := . }}
-  {{ with .TableOfContents -}}
-    {{ if ne . `<nav id="TableOfContents"></nav>` -}}
-      <div class="td-toc" data-proofer-ignore>
-        <div class="td-toc__title">
-          <span class="td-toc__title__text">On this page</span>
-          <a class="td-toc__title__link" title="Top of page" href="#"></a>
-        </div>
-        {{ $toc := . -}}
-        {{ if $safeIds -}}
-          {{/* Adjust any href values that start with a digit by adding a prefixing */ -}}
-          {{ $toc = replaceRE `(href="#)([0-9])` "${1}_toc_id_patch_$2" $toc -}}
-        {{ else if $scrollSpyEnabled -}}
-          {{ with findRE `href="#[0-9][^"]*"` . -}}
-            {{ $msg := slice
-              (printf "%s: TOC contains href that may cause ScrollSpy to fail: %s." $page.File.Filename .)
-              "For details, see https://www.docsy.dev/blog/2025/0.13.0/."
-            -}}
-            {{ warnidf "scrollspy-toc-href" "[Docsy] %s" (delimit $msg " ") -}}
-          {{ end -}}
-        {{ end -}}
-        {{ $toc | safeHTML }}
-      </div>
+  {{ $toc := .TableOfContents -}}
+  {{ if and $toc (ne $toc `<nav id="TableOfContents"></nav>`) -}}
+    {{ $scrollSpyEnabled := not (.Param "ui.scrollSpy.disable") -}}
+    {{ $safeIds := .Param "ui.scrollSpy.safeIds" | default $scrollSpyEnabled -}}
+    <div class="td-toc__title">
+      <span class="td-toc__title__text">On this page</span>
+      <a class="td-toc__title__link" title="Top of page" href="#"></a>
+    </div>
+    {{ if $safeIds -}}
+      {{/* Adjust any href values that start with a digit by adding a prefixing */ -}}
+      {{ $toc = replaceRE `(href="#)([0-9])` "${1}_toc_id_patch_$2" $toc -}}
+    {{ else if $scrollSpyEnabled -}}
+      {{ with findRE `href="#[0-9][^"]*"` . -}}
+        {{ $msg := slice
+          (printf "%s: TOC contains href that may cause ScrollSpy to fail: %s." .File.Filename .)
+          "For details, see https://www.docsy.dev/blog/2025/0.13.0/."
+        -}}
+        {{ warnidf "scrollspy-toc-href" "[Docsy] %s" (delimit $msg " ") -}}
+      {{ end -}}
     {{ end -}}
+    {{ $toc | safeHTML }}
   {{ end -}}
 {{ end -}}
+</div>
+{{/* */ -}}

package.json

@@ -1,6 +1,6 @@
 {
   "name": "docsy",
-  "version": "0.13.0-dev+50-gf23f1ab",
+  "version": "0.13.0-dev+51-g7727c79",
   "repository": "github:google/docsy",
   "homepage": "https://www.docsy.dev",
   "license": "Apache-2.0",