1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
|
package handlers
import (
"html/template"
"net/http"
"os"
"path/filepath"
"sort"
"strings"
"github.com/go-chi/chi/v5"
"github.com/yuin/goldmark"
)
// docsCategories are the only subdirectories served under /docs -- a
// whitelist, not a filesystem listing, so an unexpected file dropped into
// DocsDir doesn't unintentionally become servable.
var docsCategories = []string{"specs", "plans"}
type docsEntry struct {
Name string // filename, e.g. "2026-07-14-foo-design.md"
URL string
}
type docsCategoryListing struct {
Name string
Entries []docsEntry
}
// HandleDocsIndex lists every markdown file under each whitelisted category
// subdirectory of cfg.DocsDir, newest first (filenames are date-prefixed,
// so reverse-alphabetical is reverse-chronological).
func (h *Handler) HandleDocsIndex(w http.ResponseWriter, r *http.Request) {
var categories []docsCategoryListing
for _, cat := range docsCategories {
files, err := os.ReadDir(filepath.Join(h.config.DocsDir, cat))
if err != nil {
continue
}
var entries []docsEntry
for _, f := range files {
if f.IsDir() || !strings.HasSuffix(f.Name(), ".md") {
continue
}
entries = append(entries, docsEntry{
Name: f.Name(),
URL: "/docs/" + cat + "/" + f.Name(),
})
}
sort.Slice(entries, func(i, j int) bool { return entries[i].Name > entries[j].Name })
categories = append(categories, docsCategoryListing{Name: cat, Entries: entries})
}
if err := h.renderer.Render(w, "docs-index.html", struct {
Categories []docsCategoryListing
}{categories}); err != nil {
http.Error(w, "Failed to render template", http.StatusInternalServerError)
}
}
// HandleDocsView renders a single markdown file to HTML. category and
// filename both come from the URL and are validated against a whitelist /
// base-name check before touching the filesystem, so a request can't
// escape DocsDir via "..": chi's {filename} route param never contains a
// literal "/", and Go's filepath.Base further strips any residual path
// separators before the read.
func (h *Handler) HandleDocsView(w http.ResponseWriter, r *http.Request) {
category := chi.URLParam(r, "category")
if !isValidDocsCategory(category) {
http.NotFound(w, r)
return
}
filename := filepath.Base(chi.URLParam(r, "filename"))
if !strings.HasSuffix(filename, ".md") {
http.NotFound(w, r)
return
}
raw, err := os.ReadFile(filepath.Join(h.config.DocsDir, category, filename))
if err != nil {
http.NotFound(w, r)
return
}
var body strings.Builder
if err := goldmark.Convert(raw, &body); err != nil {
http.Error(w, "Failed to render markdown", http.StatusInternalServerError)
return
}
if err := h.renderer.Render(w, "docs-view.html", struct {
Title string
Body template.HTML
}{filename, template.HTML(body.String())}); err != nil {
http.Error(w, "Failed to render template", http.StatusInternalServerError)
}
}
func isValidDocsCategory(category string) bool {
for _, c := range docsCategories {
if c == category {
return true
}
}
return false
}
|
