fix(docs): folder-index pages expand the sidebar and highlight — same rule for every page

The filter manual is the docs tree's first FOLDER-index page: it serves
at /docs/user/filters while its nav entry carries /index
(/docs/user/filters/index). The sidebar's two checks — group expansion
(containsURL) and active-link styling (docsNavClass) — compared URLs
EXACTLY, so the folder URL matched neither: no submenu expansion, no
highlight (2026-11-01 user report: "the left sidebar should open to
the submenu and highlight the page").

Fix is structural, not per-page: both checks normalize folder-index
URLs (a trailing /index is the same page as its directory), so EVERY
folder-index page — current and future — expands and highlights like
a file page. No per-page registration exists anywhere in the docs
system to redo: the sidebar derives from the docs tree, and this was
the one URL shape its equality rule missed.

Pins: navigation (section + group expand for the folder URL, group
present) and docsNavClass (folder URL highlights the Overview item,
normalization symmetric, file pages keep their highlight, no
cross-highlighting).

templates/docs_render_test.go

@@ -144,3 +144,23 @@ func TestDocsNotFoundRenders(t *testing.T) {
 		t.Error("404 page must not pull the tailwind CDN")
 	}
 }
+
+// docsNavClass folder-index normalization (2026-11-01): folder-index
+// pages serve at their directory URL while nav entries carry /index —
+// the Overview item must highlight for the folder URL, file pages keep
+// their own highlight, and cross-highlighting stays impossible.
+func TestDocsNavClassFolderIndex(t *testing.T) {
+	active := docsNavClass("/docs/user/filters", "/docs/user/filters/index", "pl-9")
+	if !strings.Contains(active, "bg-brand/15") {
+		t.Errorf("folder-index item must highlight as active, got %q", active)
+	}
+	if !strings.Contains(docsNavClass("/docs/user/filters/index", "/docs/user/filters", "pl-9"), "bg-brand/15") {
+		t.Errorf("normalization is symmetric (either URL order highlights)")
+	}
+	if !strings.Contains(docsNavClass("/docs/user/filters/cookbook", "/docs/user/filters/cookbook", "pl-9"), "bg-brand/15") {
+		t.Error("file-page highlight regression")
+	}
+	if strings.Contains(docsNavClass("/docs/user/filters/cookbook", "/docs/user/filters/index", "pl-9"), "bg-brand/15") {
+		t.Error("cookbook URL wrongly highlights the Overview item")
+	}
+}

templates/utils.go

@@ -26,10 +26,15 @@ func activeClass(current, target string) string {
 
 // docsNavClass returns classes for docs sidebar links (server-rendered active
 // state — there is no client-side highlighter). indent sets the left padding,
-// deeper for subcategory group items.
+// deeper for subcategory group items. Folder-index pages compare normalized
+// (their serving URL lacks the /index suffix their nav entry carries).
 func docsNavClass(current, target, indent string) string {
 	base := "nav-item flex items-center " + indent + " pr-4 mr-2 py-1.5 rounded-lg text-sm transition-colors "
-	if strings.TrimRight(current, "/") == strings.TrimRight(target, "/") {
+	strip := func(u string) string {
+		u = strings.TrimRight(u, "/")
+		return strings.TrimSuffix(u, "/index")
+	}
+	if strip(current) == strip(target) {
 		return base + "bg-brand/15 text-brand font-medium"
 	}
 	return base + "text-content-muted hover:text-content hover:bg-surface-hover"