From a1ac5b1541404507c3007b5b6d0fb15c77bf8734 Mon Sep 17 00:00:00 2001
From: John O'Keefe <git@linuxhg.com>
Date: Sat, 24 Oct 2026 21:54:06 -0400
Subject: [PATCH] =?UTF-8?q?docs(ui):=20canonicalize=20.md=20URLs=20?=
 =?UTF-8?q?=E2=80=94=20sidebar=20now=20opens=20when=20arriving=20from=20ov?=
 =?UTF-8?q?erview=20links?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Root cause of 'clicked from overview, bold but menus closed': cross-page
markdown links point at area/file.md; the handler happily loads .md
URLs, but the sidebar keys on the URL path — contains-URL expansion and
the active-link styling compare against extension-less nav URLs, so a
.md path rendered the page with its menu closed and the current item
unhighlighted. (My curl checks had used clean URLs, which is why it
worked in testing but not from the overview page.)

Fix: ShowDocumentation 301-redirects .md paths to the clean canonical
form (query preserved; browsers re-attach fragments), and
renderDocPage normalizes the path for nav expansion/grouping as a belt-
and-braces. Live-verified: .../get_ratings.md -> 301 ->
clean page with both containing menus open and the get_ratings link
carrying the active class.
---
 internal/docs/http_handler.go | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

diff --git a/internal/docs/http_handler.go b/internal/docs/http_handler.go
index f18035f7..3041d33f 100644
--- a/internal/docs/http_handler.go
+++ b/internal/docs/http_handler.go
@@ -48,7 +48,10 @@ func (h *HTTPHandler) currentUser(c *echo.Context) templates.User {
 
 // renderDocPage renders a document inside the docs layout.
 func (h *HTTPHandler) renderDocPage(c *echo.Context, doc *templates.Document) error {
-	currentPath := c.Request().URL.Path
+	// .md suffixes are canonicalized to clean URLs before rendering, but
+	// normalize here too so the nav expansion + active-link styling can
+	// never see an extension the nav URLs don't carry.
+	currentPath := strings.TrimSuffix(c.Request().URL.Path, ".md")
 	nav := h.docs.BuildNavigation(currentPath)
 
 	var buf bytes.Buffer
@@ -73,6 +76,20 @@ func (h *HTTPHandler) ShowDocumentation(c *echo.Context) error {
 	// Get the document path from URL parameter
 	docPath := c.Param("*")
 
+	// Canonicalize ".md" URLs to the clean form. Markdown links across the
+	// docs tree point at `area/file.md`; the handler loads them fine, but
+	// the sidebar logic keys on the URL path (contains-URL expansion, the
+	// active-link styling) whose nav URLs are extension-less — and a raw
+	// .md path would render the page with its menu closed and the current
+	// item unhighlighted. 301 keeps the browser URL canonical.
+	if strings.HasSuffix(docPath, ".md") {
+		target := strings.TrimSuffix("/docs/"+docPath, ".md")
+		if c.Request().URL.RawQuery != "" {
+			target += "?" + c.Request().URL.RawQuery
+		}
+		return c.Redirect(http.StatusMovedPermanently, target)
+	}
+
 	// Load the document
 	doc, err := h.docs.LoadDocument(docPath)
 	if err != nil {