feat: add README preview side menu

Co-authored-by: D <code@dector.space>

Author: DCodeBot

README.md

@@ -65,7 +65,7 @@ serv .
 serv README.md
 ```
 
-In preview mode, supported Markdown files (`.md`, `.markdown`, `.mdown`, `.mkd`) render as HTML. Directories resolve `README` first, then `index.html`, then fall back to a listing.
+In preview mode, supported Markdown files (`.md`, `.markdown`, `.mdown`, `.mkd`) render as HTML. Directories resolve `README` first, then `index.html`, then fall back to a listing. Auto-resolved README previews include a foldable side menu for navigating sibling files and folders.
 
 Use file mode for raw file browsing:
 

docs/RECIPES.md

@@ -66,7 +66,7 @@ Browser opening is best-effort; if it fails, the server keeps running and prints
 serv Downloads
 ```
 
-In default preview mode, directories resolve `README` first, then `index.html`, then fall back to a listing page.
+In default preview mode, directories resolve `README` first, then `index.html`, then fall back to a listing page. Auto-resolved README previews include a foldable side menu for navigating sibling files and folders.
 
 ### Use file browsing mode
 

main.go

@@ -15,6 +15,7 @@ import (
 	"path"
 	"path/filepath"
 	"runtime"
+	"sort"
 	"strings"
 	"syscall"
 	"time"
@@ -638,18 +639,85 @@ func findReadme(fsys fs.FS, dir string) (string, bool) {
 	if err != nil {
 		return "", false
 	}
-	allowed := map[string]bool{"readme.md": true, "readme.markdown": true, "readme.mdown": true, "readme.mkd": true}
 	for _, entry := range entries {
 		if entry.IsDir() {
 			continue
 		}
-		if allowed[strings.ToLower(entry.Name())] {
+		if isReadmeName(entry.Name()) {
 			return path.Join(dir, entry.Name()), true
 		}
 	}
 	return "", false
 }
 
+func isReadmeName(name string) bool {
+	allowed := map[string]bool{"readme.md": true, "readme.markdown": true, "readme.mdown": true, "readme.mkd": true}
+	return allowed[strings.ToLower(name)]
+}
+
+func buildSideMenu(r *http.Request, dir string, currentPath string, fsys fs.FS) *preview.SideMenu {
+	menu := &preview.SideMenu{CurrentPath: displayDirPath(dir)}
+	entries, err := fs.ReadDir(fsys, dir)
+	if err != nil {
+		menu.Error = "Could not load directory menu."
+		return menu
+	}
+
+	if !isRootDirPath(dir) {
+		menu.Items = append(menu.Items, preview.SideMenuItem{
+			Label: "../",
+			Href:  sideMenuHref(r, "../"),
+			Title: "../",
+		})
+	}
+
+	sort.SliceStable(entries, func(i, j int) bool {
+		if entries[i].IsDir() != entries[j].IsDir() {
+			return entries[i].IsDir()
+		}
+		return strings.ToLower(entries[i].Name()) < strings.ToLower(entries[j].Name())
+	})
+
+	currentName := path.Base(currentPath)
+	for _, entry := range entries {
+		name := entry.Name()
+		label := name
+		href := sideMenuHref(r, name)
+		if entry.IsDir() {
+			label = name + "/"
+			href = sideMenuHref(r, name+"/")
+		}
+		menu.Items = append(menu.Items, preview.SideMenuItem{
+			Label:     label,
+			Href:      href,
+			Title:     label,
+			IsDir:     entry.IsDir(),
+			IsCurrent: !entry.IsDir() && name == currentName,
+		})
+	}
+	return menu
+}
+
+func displayDirPath(dir string) string {
+	clean := path.Clean(dir)
+	if clean == "." || clean == "/" {
+		return "/"
+	}
+	return "/" + strings.Trim(clean, "/") + "/"
+}
+
+func isRootDirPath(dir string) bool {
+	clean := path.Clean(dir)
+	return clean == "." || clean == "/"
+}
+
+func sideMenuHref(r *http.Request, href string) string {
+	if r == nil || r.URL == nil || r.URL.RawQuery == "" {
+		return href
+	}
+	return href + "?" + r.URL.RawQuery
+}
+
 func shouldRenderPreview(r *http.Request, requestedPath string, mode serveMode) bool {
 	if !preview.CanPreview(requestedPath) {
 		return false
@@ -699,6 +767,12 @@ func serveFolder(lw http.ResponseWriter, r *http.Request, requestedPath string,
 	strategy := requestDirResolveStrategy(r, config.DirResolve)
 	if strategy != dirResolveNone {
 		if candidate, ok := selectDirectoryCandidate(fsys, requestedPath, strategy); ok {
+			if isReadmeName(path.Base(candidate)) && shouldRenderPreview(r, candidate, config.Mode) {
+				if err := servePreviewFile(lw, r, candidate, fsys, preview.Options{SideMenu: buildSideMenu(r, requestedPath, candidate, fsys)}); err != nil {
+					serveFileError(lw, r, "Serve error", err, directoryRecoveryLinks(strategy))
+				}
+				return
+			}
 			if err := serveFile(lw, r, candidate, fsys, config); err != nil {
 				serveFileError(lw, r, "Serve error", err, directoryRecoveryLinks(strategy))
 			}
@@ -727,14 +801,7 @@ func serveFile(lw http.ResponseWriter, r *http.Request, requestedPath string, fs
 	}
 
 	if shouldRenderPreview(r, requestedPath, config.Mode) {
-		rendered, err := preview.Render(requestedPath, content)
-		if err != nil {
-			serveFileError(lw, r, "Preview error", err, []recoveryLink{{Label: "View raw file", Query: "raw=1"}})
-			return nil
-		}
-		lw.Header().Set("Content-Type", "text/html; charset=utf-8")
-		_, err = lw.Write(rendered)
-		return err
+		return writePreview(lw, r, requestedPath, content, preview.Options{})
 	}
 
 	// Serve the file using MIME-by-extension behavior for raw responses.
@@ -746,6 +813,25 @@ func serveFile(lw http.ResponseWriter, r *http.Request, requestedPath string, fs
 	return err
 }
 
+func servePreviewFile(lw http.ResponseWriter, r *http.Request, requestedPath string, fsys fs.FS, options preview.Options) error {
+	content, err := fs.ReadFile(fsys, requestedPath)
+	if err != nil {
+		return err
+	}
+	return writePreview(lw, r, requestedPath, content, options)
+}
+
+func writePreview(lw http.ResponseWriter, r *http.Request, requestedPath string, content []byte, options preview.Options) error {
+	rendered, err := preview.RenderWithOptions(requestedPath, content, options)
+	if err != nil {
+		serveFileError(lw, r, "Preview error", err, []recoveryLink{{Label: "View raw file", Query: "raw=1"}})
+		return nil
+	}
+	lw.Header().Set("Content-Type", "text/html; charset=utf-8")
+	_, err = lw.Write(rendered)
+	return err
+}
+
 func serveFileError(lw http.ResponseWriter, r *http.Request, title string, err error, links []recoveryLink) {
 	lw.Header().Set("Content-Type", "text/html; charset=utf-8")
 	lw.WriteHeader(http.StatusInternalServerError)

main_test.go

@@ -243,3 +243,88 @@ func TestServeFolderPreviewDefaultServesReadmeBeforeIndex(t *testing.T) {
 		t.Fatalf("body = %s, want README preview", body)
 	}
 }
+
+func TestServeFolderReadmePreviewIncludesSideMenu(t *testing.T) {
+	root := t.TempDir()
+	rootInfo, err := fstest.MapFS{"docs": &fstest.MapFile{Mode: 0755 | fs.ModeDir}}.Stat("docs")
+	if err != nil {
+		t.Fatalf("stat root: %v", err)
+	}
+	fsys := fstest.MapFS{
+		"docs":           &fstest.MapFile{Mode: 0755 | fs.ModeDir},
+		"docs/README.md": &fstest.MapFile{Data: []byte("# Readme")},
+		"docs/a.txt":     &fstest.MapFile{Data: []byte("a")},
+		"docs/sub":       &fstest.MapFile{Mode: 0755 | fs.ModeDir},
+	}
+	r := httptest.NewRequest(http.MethodGet, "/docs/?preview=1&resolve=readme-only", nil)
+	w := httptest.NewRecorder()
+
+	serveFolder(w, r, "docs", fsys, rootInfo, root, serveConfig{Mode: serveModeFile, DirResolve: dirResolveReadmeFirst})
+
+	bodyBytes, _ := io.ReadAll(w.Result().Body)
+	body := string(bodyBytes)
+	for _, want := range []string{"<nav class=\"side-menu\"", "/docs/", "../?preview=1&amp;resolve=readme-only", "sub/?preview=1&amp;resolve=readme-only", "a.txt?preview=1&amp;resolve=readme-only", "[dir]", "side-menu__item--current"} {
+		if !strings.Contains(body, want) {
+			t.Fatalf("body missing %q: %s", want, body)
+		}
+	}
+	if strings.Contains(body, "href=\"README.md") {
+		t.Fatalf("current README should not be a link: %s", body)
+	}
+}
+
+func TestServeFileDirectReadmePreviewOmitsSideMenu(t *testing.T) {
+	fsys := fstest.MapFS{"README.md": &fstest.MapFile{Data: []byte("# Title")}}
+	r := httptest.NewRequest(http.MethodGet, "/README.md", nil)
+	w := httptest.NewRecorder()
+
+	serveFile(w, r, "README.md", fsys, serveConfig{Mode: serveModePreview})
+
+	body, _ := io.ReadAll(w.Result().Body)
+	if strings.Contains(string(body), "<nav class=\"side-menu\"") {
+		t.Fatalf("direct README preview should not include side menu: %s", body)
+	}
+}
+
+func TestServeFolderIndexPreviewOmitsSideMenu(t *testing.T) {
+	root := t.TempDir()
+	rootInfo, err := fstest.MapFS{"docs": &fstest.MapFile{Mode: 0755 | fs.ModeDir}}.Stat("docs")
+	if err != nil {
+		t.Fatalf("stat root: %v", err)
+	}
+	fsys := fstest.MapFS{
+		"docs":            &fstest.MapFile{Mode: 0755 | fs.ModeDir},
+		"docs/README.md":  &fstest.MapFile{Data: []byte("# Readme")},
+		"docs/index.html": &fstest.MapFile{Data: []byte("<h1>Index</h1>")},
+	}
+	r := httptest.NewRequest(http.MethodGet, "/docs/?resolve=index-only", nil)
+	w := httptest.NewRecorder()
+
+	serveFolder(w, r, "docs", fsys, rootInfo, root, serveConfig{Mode: serveModePreview, DirResolve: dirResolveReadmeFirst})
+
+	body, _ := io.ReadAll(w.Result().Body)
+	if strings.Contains(string(body), "<nav class=\"side-menu\"") {
+		t.Fatalf("index resolution should not include side menu: %s", body)
+	}
+}
+
+func TestServeFolderRawReadmeOmitsSideMenu(t *testing.T) {
+	root := t.TempDir()
+	rootInfo, err := fstest.MapFS{"docs": &fstest.MapFile{Mode: 0755 | fs.ModeDir}}.Stat("docs")
+	if err != nil {
+		t.Fatalf("stat root: %v", err)
+	}
+	fsys := fstest.MapFS{
+		"docs":           &fstest.MapFile{Mode: 0755 | fs.ModeDir},
+		"docs/README.md": &fstest.MapFile{Data: []byte("# Readme")},
+	}
+	r := httptest.NewRequest(http.MethodGet, "/docs/?raw=1", nil)
+	w := httptest.NewRecorder()
+
+	serveFolder(w, r, "docs", fsys, rootInfo, root, serveConfig{Mode: serveModePreview, DirResolve: dirResolveReadmeFirst})
+
+	body, _ := io.ReadAll(w.Result().Body)
+	if got := string(body); got != "# Readme" {
+		t.Fatalf("body = %q, want raw README", got)
+	}
+}

preview/preview.go

@@ -26,6 +26,37 @@ func CanPreview(name string) bool {
 
 // Render renders name/content with the default renderer.
 func Render(name string, content []byte) ([]byte, error) {
+	return RenderWithOptions(name, content, Options{})
+}
+
+// Options configures optional preview page features.
+type Options struct {
+	SideMenu *SideMenu
+}
+
+// SideMenu describes an optional directory navigation menu.
+type SideMenu struct {
+	CurrentPath string
+	Items       []SideMenuItem
+	Error       string
+}
+
+// SideMenuItem describes one directory navigation menu item.
+type SideMenuItem struct {
+	Label     string
+	Href      string
+	Title     string
+	IsDir     bool
+	IsCurrent bool
+}
+
+// RenderWithOptions renders name/content with optional page features.
+func RenderWithOptions(name string, content []byte, options Options) ([]byte, error) {
+	if renderer, ok := defaultRenderer.(interface {
+		RenderWithOptions(string, []byte, Options) ([]byte, error)
+	}); ok {
+		return renderer.RenderWithOptions(name, content, options)
+	}
 	return defaultRenderer.Render(name, content)
 }
 
@@ -43,7 +74,12 @@ func (MarkdownRenderer) CanPreview(name string) bool {
 }
 
 // Render renders Markdown content to a self-contained dark HTML page.
-func (MarkdownRenderer) Render(name string, content []byte) ([]byte, error) {
+func (r MarkdownRenderer) Render(name string, content []byte) ([]byte, error) {
+	return r.RenderWithOptions(name, content, Options{})
+}
+
+// RenderWithOptions renders Markdown content to a self-contained dark HTML page with optional page features.
+func (MarkdownRenderer) RenderWithOptions(name string, content []byte, options Options) ([]byte, error) {
 	md := goldmark.New(
 		goldmark.WithExtensions(
 			extension.Table,
@@ -60,19 +96,21 @@ func (MarkdownRenderer) Render(name string, content []byte) ([]byte, error) {
 
 	var page bytes.Buffer
 	if err := pageTemplate.Execute(&page, pageData{
-		Title: filepath.Base(name),
-		Body:  template.HTML(body.String()),
-		Theme: theme.Dark,
+		Title:    filepath.Base(name),
+		Body:     template.HTML(body.String()),
+		Theme:    theme.Dark,
+		SideMenu: options.SideMenu,
 	}); err != nil {
 		return nil, err
 	}
 	return page.Bytes(), nil
 }
 
 type pageData struct {
-	Title string
-	Body  template.HTML
-	Theme theme.Colors
+	Title    string
+	Body     template.HTML
+	Theme    theme.Colors
+	SideMenu *SideMenu
 }
 
 var pageTemplate = template.Must(template.New("preview").Parse(`<!doctype html>
@@ -83,15 +121,26 @@ var pageTemplate = template.Must(template.New("preview").Parse(`<!doctype html>
 <title>{{.Title}}</title>
 <style>
 :root{color-scheme:dark;--bg:{{.Theme.Background}};--panel:{{.Theme.Panel}};--text:{{.Theme.Text}};--muted:{{.Theme.Muted}};--border:{{.Theme.Border}};--accent:{{.Theme.Accent}};--code:{{.Theme.Code}}}
-*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--text);font:16px/1.6 system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif}.topbar,.footer{background:var(--panel);border-color:var(--border);color:var(--muted)}.topbar{border-bottom:1px solid var(--border);padding:12px 24px;font-weight:600}.footer{border-top:1px solid var(--border);padding:16px 24px;text-align:center}.content{max-width:920px;margin:0 auto;padding:32px 24px 56px}a{color:var(--accent)}h1,h2,h3,h4,h5,h6{line-height:1.25;margin:1.5em 0 .6em}h1,h2{border-bottom:1px solid var(--border);padding-bottom:.3em}p,ul,ol,blockquote,pre,table{margin:0 0 1em}blockquote{border-left:4px solid var(--border);color:var(--muted);padding:0 1em}code{background:rgba(110,118,129,.28);border-radius:6px;padding:.2em .4em;font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}pre{background:var(--code);border:1px solid var(--border);border-radius:8px;overflow:auto;padding:16px}pre code{background:transparent;padding:0}table{border-collapse:collapse;width:100%;display:block;overflow:auto}th,td{border:1px solid var(--border);padding:6px 13px}th{background:var(--panel)}img{max-width:100%}hr{border:0;border-top:1px solid var(--border);margin:24px 0}.task-list-item{list-style-type:none}.task-list-item input{margin:0 .5em 0 -1.4em}
+*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--text);font:16px/1.6 system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif}.topbar,.footer{background:var(--panel);border-color:var(--border);color:var(--muted)}.topbar{border-bottom:1px solid var(--border);padding:12px 24px;font-weight:600}.footer{border-top:1px solid var(--border);padding:16px 24px;text-align:center}.page-shell{display:flex;min-height:calc(100vh - 50px)}.content{max-width:920px;margin:0 auto;padding:32px 24px 56px;flex:1;min-width:0}.side-menu{background:var(--panel);border-right:1px solid var(--border);flex:0 0 260px;width:260px;max-height:calc(100vh - 50px);overflow:auto;position:sticky;top:0;align-self:flex-start}.side-menu__header{border-bottom:1px solid var(--border);color:var(--muted);font-size:13px;font-weight:600;overflow:hidden;padding:12px 16px;text-overflow:ellipsis;white-space:nowrap}.side-menu__list{list-style:none;margin:0;padding:8px}.side-menu__item{border-radius:6px;color:var(--muted);display:block;overflow:hidden;padding:6px 8px;text-overflow:ellipsis;white-space:nowrap}.side-menu__item a{display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.side-menu__item--current{background:rgba(110,118,129,.18);color:var(--text);font-weight:600}.side-menu__kind{color:var(--muted);font-size:12px;margin-right:6px}.side-menu__error{color:var(--muted);padding:12px 16px}.side-menu-toggle{background:var(--panel);border:1px solid var(--border);color:var(--text);cursor:pointer;z-index:3}.side-menu__collapse{border-radius:999px;height:28px;position:absolute;right:-14px;top:50%;transform:translateY(-50%);width:28px}.side-menu__expand{border-left:0;border-radius:0 999px 999px 0;display:none;left:0;padding:16px 6px;position:fixed;top:50%;transform:translateY(-50%)}body.side-menu-collapsed .side-menu{display:none}body.side-menu-collapsed .side-menu__expand{display:block}@media(max-width:760px){.page-shell{display:block}.side-menu{bottom:0;box-shadow:0 0 0 9999px rgba(0,0,0,.45);left:0;max-height:none;position:fixed;top:0;z-index:2}body.side-menu-collapsed .side-menu{display:none}}a{color:var(--accent)}h1,h2,h3,h4,h5,h6{line-height:1.25;margin:1.5em 0 .6em}h1,h2{border-bottom:1px solid var(--border);padding-bottom:.3em}p,ul,ol,blockquote,pre,table{margin:0 0 1em}blockquote{border-left:4px solid var(--border);color:var(--muted);padding:0 1em}code{background:rgba(110,118,129,.28);border-radius:6px;padding:.2em .4em;font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}pre{background:var(--code);border:1px solid var(--border);border-radius:8px;overflow:auto;padding:16px}pre code{background:transparent;padding:0}table{border-collapse:collapse;width:100%;display:block;overflow:auto}th,td{border:1px solid var(--border);padding:6px 13px}th{background:var(--panel)}img{max-width:100%}hr{border:0;border-top:1px solid var(--border);margin:24px 0}.task-list-item{list-style-type:none}.task-list-item input{margin:0 .5em 0 -1.4em}
 </style>
 </head>
 <body>
 <header class="topbar">{{.Title}}</header>
+{{if .SideMenu}}<button class="side-menu-toggle side-menu__expand" type="button" aria-label="Show directory menu">›</button>{{end}}
+<div class="page-shell">
+{{with .SideMenu}}<nav class="side-menu" aria-label="Directory menu">
+<button class="side-menu-toggle side-menu__collapse" type="button" aria-label="Hide directory menu">‹</button>
+<div class="side-menu__header" title="{{.CurrentPath}}">{{.CurrentPath}}</div>
+{{if .Error}}<div class="side-menu__error">{{.Error}}</div>{{else}}<ul class="side-menu__list">
+{{range .Items}}<li class="side-menu__item{{if .IsCurrent}} side-menu__item--current{{end}}" title="{{.Title}}">{{if .IsCurrent}}{{if .IsDir}}<span class="side-menu__kind">[dir]</span>{{end}}{{.Label}}{{else}}<a href="{{.Href}}" title="{{.Title}}">{{if .IsDir}}<span class="side-menu__kind">[dir]</span>{{end}}{{.Label}}</a>{{end}}</li>{{end}}
+</ul>{{end}}
+</nav>{{end}}
 <main class="content">
 {{.Body}}
 </main>
+</div>
 <footer class="footer">served by serv</footer>
+{{if .SideMenu}}<script>(function(){var key='serv.sideMenuCollapsed';var body=document.body;var apply=function(v){body.classList.toggle('side-menu-collapsed',v==='1')};try{apply(localStorage.getItem(key))}catch(e){}function set(v){apply(v?'1':'0');try{localStorage.setItem(key,v?'1':'0')}catch(e){}}document.querySelectorAll('.side-menu__collapse').forEach(function(b){b.addEventListener('click',function(){set(true)})});document.querySelectorAll('.side-menu__expand').forEach(function(b){b.addEventListener('click',function(){set(false)})});})();</script>{{end}}
 </body>
 </html>
 `))