initial: zero-trust markdown tutorials site
Single-binary Go service that renders markdown pages from a runtime volume mount. Targeted at public, no-auth, no-WAF deployment behind a TLS ingress; security posture is defense-in-depth at every layer: - goldmark with no WithUnsafe — raw HTML in author markdown is stripped - CSP without 'unsafe-inline', plus HSTS, COOP, CORP, Permissions-Policy - static handler rejects non-GET/HEAD, directory listings, dotfiles, traversal - content loader rejects symlinks that escape the content root, dotfiles, and .md files larger than 1 MiB - per-page template trees (cloned from layout) so define-blocks don't collide between home/category/page - SIGHUP triggers atomic library swap — live edits on volume, no rebuild Locale layout content/<locale>/<category>/<slug>.md. Categories without _index.md still appear on the home page with a humanized name. Search is a ~70-line vanilla JS scan over /search.json?lang=<locale>; swap for a real indexer if the corpus ever balloons. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,322 @@
|
||||
// Package content loads and indexes markdown tutorial pages from disk.
|
||||
//
|
||||
// Layout on disk:
|
||||
//
|
||||
// content/
|
||||
// <locale>/ — e.g. en, cs
|
||||
// <category>/ — e.g. install-client, registration, troubleshooting
|
||||
// _index.md — category landing page (optional)
|
||||
// <slug>.md — individual tutorial page
|
||||
//
|
||||
// Each markdown file may have YAML frontmatter delimited by `---`:
|
||||
//
|
||||
// ---
|
||||
// title: Install Minecraft Java Edition
|
||||
// order: 1
|
||||
// summary: Step-by-step for installing the official launcher.
|
||||
// ---
|
||||
// # heading...
|
||||
//
|
||||
// Pages without frontmatter use the filename as title and order=999.
|
||||
package content
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"sort"
|
||||
"strings"
|
||||
|
||||
"gopkg.in/yaml.v3"
|
||||
)
|
||||
|
||||
// Library is an in-memory index of all loaded pages. Construct via Load.
|
||||
// Read-only after construction; the server swaps whole Library values on reload.
|
||||
type Library struct {
|
||||
pages map[string]*Page // key: <locale>/<category>/<slug>
|
||||
byPath map[string][]*Page // key: <locale>/<category>, value: pages sorted by Order then Title
|
||||
locales []string // sorted, unique
|
||||
categs map[string]map[string]*Page // <locale> → <category> → category-index page (or nil if no _index.md)
|
||||
}
|
||||
|
||||
// maxPageBytes caps the size of a single markdown file. Loader skips bigger files with a stderr warning.
|
||||
// Content is operator-controlled (volume mount), but this prevents a stray dump from ballooning memory.
|
||||
const maxPageBytes = 1 << 20 // 1 MiB
|
||||
|
||||
// Page is one markdown document.
|
||||
type Page struct {
|
||||
Locale string // "en", "cs"
|
||||
Category string // "install-client"
|
||||
Slug string // "java-edition", "_index"
|
||||
Title string
|
||||
Summary string
|
||||
Order int
|
||||
Source []byte // raw markdown body (no frontmatter)
|
||||
Path string // <locale>/<category>/<slug>
|
||||
}
|
||||
|
||||
type frontmatter struct {
|
||||
Title string `yaml:"title"`
|
||||
Summary string `yaml:"summary"`
|
||||
Order int `yaml:"order"`
|
||||
}
|
||||
|
||||
// Load walks contentDir and returns a populated Library.
|
||||
// Returns an error only on filesystem-level failures; individual malformed pages are skipped with a warning written to stderr.
|
||||
//
|
||||
// Zero-trust posture: the content dir is volume-mounted in production. The loader
|
||||
// resolves the absolute path of contentDir once and rejects any entry (dir or file)
|
||||
// whose evaluated symlink target falls outside it. This prevents a misconfigured
|
||||
// volume (or an operator slipping in a symlink) from reading host files.
|
||||
func Load(contentDir string) (*Library, error) {
|
||||
info, err := os.Stat(contentDir)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("stat content dir %q: %w", contentDir, err)
|
||||
}
|
||||
if !info.IsDir() {
|
||||
return nil, fmt.Errorf("content path %q is not a directory", contentDir)
|
||||
}
|
||||
rootAbs, err := filepath.Abs(contentDir)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("abs content dir: %w", err)
|
||||
}
|
||||
rootAbs, err = filepath.EvalSymlinks(rootAbs)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("eval root symlinks: %w", err)
|
||||
}
|
||||
|
||||
lib := &Library{
|
||||
pages: make(map[string]*Page),
|
||||
byPath: make(map[string][]*Page),
|
||||
categs: make(map[string]map[string]*Page),
|
||||
}
|
||||
|
||||
localeEntries, err := os.ReadDir(contentDir)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("read content dir: %w", err)
|
||||
}
|
||||
for _, lEntry := range localeEntries {
|
||||
name := lEntry.Name()
|
||||
if strings.HasPrefix(name, ".") || !lEntry.IsDir() {
|
||||
continue
|
||||
}
|
||||
localeDir := filepath.Join(contentDir, name)
|
||||
if !withinRoot(rootAbs, localeDir) {
|
||||
fmt.Fprintf(os.Stderr, "[content] skipping locale %q: escapes content root\n", name)
|
||||
continue
|
||||
}
|
||||
lib.locales = append(lib.locales, name)
|
||||
lib.categs[name] = make(map[string]*Page)
|
||||
|
||||
categEntries, err := os.ReadDir(localeDir)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("read locale %q: %w", name, err)
|
||||
}
|
||||
for _, cEntry := range categEntries {
|
||||
cName := cEntry.Name()
|
||||
if strings.HasPrefix(cName, ".") || !cEntry.IsDir() {
|
||||
continue
|
||||
}
|
||||
categDir := filepath.Join(localeDir, cName)
|
||||
if !withinRoot(rootAbs, categDir) {
|
||||
fmt.Fprintf(os.Stderr, "[content] skipping %s/%s: escapes content root\n", name, cName)
|
||||
continue
|
||||
}
|
||||
// Register the category even if _index.md is missing; it'll show up
|
||||
// on the home page with a humanized name.
|
||||
if _, ok := lib.categs[name][cName]; !ok {
|
||||
lib.categs[name][cName] = nil
|
||||
}
|
||||
if err := lib.loadCategory(rootAbs, name, cName, categDir); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
sort.Strings(lib.locales)
|
||||
for k := range lib.byPath {
|
||||
pages := lib.byPath[k]
|
||||
sort.SliceStable(pages, func(i, j int) bool {
|
||||
if pages[i].Order != pages[j].Order {
|
||||
return pages[i].Order < pages[j].Order
|
||||
}
|
||||
return pages[i].Title < pages[j].Title
|
||||
})
|
||||
lib.byPath[k] = pages
|
||||
}
|
||||
return lib, nil
|
||||
}
|
||||
|
||||
// withinRoot returns true if p, after resolving symlinks, is rootAbs or a descendant.
|
||||
// Used to reject volume entries that point outside the content directory.
|
||||
func withinRoot(rootAbs, p string) bool {
|
||||
abs, err := filepath.Abs(p)
|
||||
if err != nil {
|
||||
return false
|
||||
}
|
||||
resolved, err := filepath.EvalSymlinks(abs)
|
||||
if err != nil {
|
||||
return false
|
||||
}
|
||||
rel, err := filepath.Rel(rootAbs, resolved)
|
||||
if err != nil {
|
||||
return false
|
||||
}
|
||||
return rel == "." || (!strings.HasPrefix(rel, "..") && !filepath.IsAbs(rel))
|
||||
}
|
||||
|
||||
func (l *Library) loadCategory(rootAbs, locale, category, dir string) error {
|
||||
files, err := os.ReadDir(dir)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
pathKey := locale + "/" + category
|
||||
for _, f := range files {
|
||||
name := f.Name()
|
||||
if strings.HasPrefix(name, ".") || f.IsDir() || !strings.HasSuffix(name, ".md") {
|
||||
continue
|
||||
}
|
||||
fp := filepath.Join(dir, name)
|
||||
if !withinRoot(rootAbs, fp) {
|
||||
fmt.Fprintf(os.Stderr, "[content] skipping %s: escapes content root\n", fp)
|
||||
continue
|
||||
}
|
||||
// Use Stat on the resolved path to enforce size cap before reading.
|
||||
info, err := os.Stat(fp)
|
||||
if err != nil {
|
||||
fmt.Fprintf(os.Stderr, "[content] stat %s: %v\n", fp, err)
|
||||
continue
|
||||
}
|
||||
if info.Size() > maxPageBytes {
|
||||
fmt.Fprintf(os.Stderr, "[content] skipping %s: %d bytes exceeds %d cap\n", fp, info.Size(), maxPageBytes)
|
||||
continue
|
||||
}
|
||||
slug := strings.TrimSuffix(name, ".md")
|
||||
raw, err := os.ReadFile(fp)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
page, err := parsePage(raw, locale, category, slug)
|
||||
if err != nil {
|
||||
fmt.Fprintf(os.Stderr, "[content] skipping %s: %v\n", fp, err)
|
||||
continue
|
||||
}
|
||||
key := page.Path
|
||||
l.pages[key] = page
|
||||
if slug == "_index" {
|
||||
l.categs[locale][category] = page
|
||||
} else {
|
||||
l.byPath[pathKey] = append(l.byPath[pathKey], page)
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func parsePage(raw []byte, locale, category, slug string) (*Page, error) {
|
||||
body := raw
|
||||
fm := frontmatter{Order: 999}
|
||||
if bytes := raw; len(bytes) >= 4 && string(bytes[:3]) == "---" {
|
||||
// Find closing fence on its own line.
|
||||
rest := bytes[3:]
|
||||
idx := strings.Index(string(rest), "\n---")
|
||||
if idx >= 0 {
|
||||
head := rest[:idx]
|
||||
if err := yaml.Unmarshal(head, &fm); err != nil {
|
||||
return nil, fmt.Errorf("frontmatter: %w", err)
|
||||
}
|
||||
body = rest[idx+4:]
|
||||
body = trimLeadingNewline(body)
|
||||
}
|
||||
}
|
||||
if fm.Title == "" {
|
||||
fm.Title = slugToTitle(slug)
|
||||
}
|
||||
return &Page{
|
||||
Locale: locale,
|
||||
Category: category,
|
||||
Slug: slug,
|
||||
Title: fm.Title,
|
||||
Summary: fm.Summary,
|
||||
Order: fm.Order,
|
||||
Source: body,
|
||||
Path: locale + "/" + category + "/" + slug,
|
||||
}, nil
|
||||
}
|
||||
|
||||
func trimLeadingNewline(b []byte) []byte {
|
||||
if len(b) > 0 && b[0] == '\n' {
|
||||
return b[1:]
|
||||
}
|
||||
return b
|
||||
}
|
||||
|
||||
func slugToTitle(slug string) string {
|
||||
s := strings.ReplaceAll(slug, "-", " ")
|
||||
s = strings.ReplaceAll(s, "_", " ")
|
||||
if s == "" {
|
||||
return ""
|
||||
}
|
||||
return strings.ToUpper(s[:1]) + s[1:]
|
||||
}
|
||||
|
||||
// --- Accessors ---
|
||||
|
||||
func (l *Library) Locales() []string { return append([]string(nil), l.locales...) }
|
||||
func (l *Library) PageCount() int { return len(l.pages) }
|
||||
func (l *Library) HasLocale(loc string) bool {
|
||||
_, ok := l.categs[loc]
|
||||
return ok
|
||||
}
|
||||
|
||||
// Categories returns the categories in a locale, sorted by their _index.Order then name.
|
||||
type Category struct {
|
||||
Name string
|
||||
Index *Page // may be nil if no _index.md
|
||||
Pages []*Page
|
||||
}
|
||||
|
||||
func (l *Library) Categories(locale string) []Category {
|
||||
cats, ok := l.categs[locale]
|
||||
if !ok {
|
||||
return nil
|
||||
}
|
||||
var out []Category
|
||||
for name := range cats {
|
||||
idx := cats[name]
|
||||
out = append(out, Category{
|
||||
Name: name,
|
||||
Index: idx,
|
||||
Pages: l.byPath[locale+"/"+name],
|
||||
})
|
||||
}
|
||||
// Stable order: by index Order, then name.
|
||||
sort.SliceStable(out, func(i, j int) bool {
|
||||
oi, oj := 999, 999
|
||||
if out[i].Index != nil {
|
||||
oi = out[i].Index.Order
|
||||
}
|
||||
if out[j].Index != nil {
|
||||
oj = out[j].Index.Order
|
||||
}
|
||||
if oi != oj {
|
||||
return oi < oj
|
||||
}
|
||||
return out[i].Name < out[j].Name
|
||||
})
|
||||
return out
|
||||
}
|
||||
|
||||
// Page returns the page for a path or nil.
|
||||
func (l *Library) Page(locale, category, slug string) *Page {
|
||||
return l.pages[locale+"/"+category+"/"+slug]
|
||||
}
|
||||
|
||||
// AllPages returns every page; used by the search index endpoint.
|
||||
func (l *Library) AllPages() []*Page {
|
||||
out := make([]*Page, 0, len(l.pages))
|
||||
for _, p := range l.pages {
|
||||
out = append(out, p)
|
||||
}
|
||||
sort.Slice(out, func(i, j int) bool { return out[i].Path < out[j].Path })
|
||||
return out
|
||||
}
|
||||
@@ -0,0 +1,35 @@
|
||||
// Package render converts markdown to HTML using goldmark.
|
||||
//
|
||||
// Zero-trust posture: raw HTML in markdown is escaped. Even though content comes from
|
||||
// an operator-mounted volume (not a request), defense-in-depth keeps a stray <script>
|
||||
// or <iframe> in a tutorial from running in a visitor's browser. Authors get goldmark
|
||||
// + GFM + footnotes; raw HTML in .md is rendered as text.
|
||||
package render
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
|
||||
"github.com/yuin/goldmark"
|
||||
"github.com/yuin/goldmark/extension"
|
||||
"github.com/yuin/goldmark/parser"
|
||||
)
|
||||
|
||||
var md = goldmark.New(
|
||||
goldmark.WithExtensions(
|
||||
extension.GFM, // tables, strikethrough, autolink, tasklist
|
||||
extension.Footnote,
|
||||
),
|
||||
goldmark.WithParserOptions(
|
||||
parser.WithAutoHeadingID(),
|
||||
),
|
||||
// No WithUnsafe() — raw HTML stays escaped.
|
||||
)
|
||||
|
||||
// Markdown renders a markdown body to HTML.
|
||||
func Markdown(source []byte) (string, error) {
|
||||
var buf bytes.Buffer
|
||||
if err := md.Convert(source, &buf); err != nil {
|
||||
return "", err
|
||||
}
|
||||
return buf.String(), nil
|
||||
}
|
||||
@@ -0,0 +1,344 @@
|
||||
// Package server is the HTTP layer: route mux, page handlers, search index endpoint.
|
||||
//
|
||||
// Routing:
|
||||
//
|
||||
// GET / → redirect to /<defaultLocale>/
|
||||
// GET /<locale>/ → home (lists categories)
|
||||
// GET /<locale>/<category>/ → category landing (lists pages)
|
||||
// GET /<locale>/<category>/<slug> → render single page
|
||||
// GET /search.json → ?lang=<locale> returns search index for client-side FlexSearch
|
||||
// GET /static/... → bundled CSS / htmx.min.js
|
||||
// GET /healthz → liveness
|
||||
package server
|
||||
|
||||
import (
|
||||
"context"
|
||||
"embed"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"fmt"
|
||||
"html/template"
|
||||
"io/fs"
|
||||
"log/slog"
|
||||
"net/http"
|
||||
"strings"
|
||||
"sync/atomic"
|
||||
"time"
|
||||
|
||||
"git.timemachine.center/Timemachine/automc-tutorials/internal/content"
|
||||
"git.timemachine.center/Timemachine/automc-tutorials/internal/render"
|
||||
)
|
||||
|
||||
//go:embed all:templates
|
||||
var templatesFS embed.FS
|
||||
|
||||
//go:embed all:static
|
||||
var staticFS embed.FS
|
||||
|
||||
// Server holds the swappable library + per-page template trees + default locale.
|
||||
// SwapLibrary is used by SIGHUP-driven reload in main.go.
|
||||
//
|
||||
// Templates are parsed as one base tree (layout.html) plus a clone per page
|
||||
// template so that `{{define "title"}}` / `{{define "content"}}` blocks from
|
||||
// home/category/page don't overwrite each other. Rendering invokes the
|
||||
// "layout" template name from the page-specific tree.
|
||||
type Server struct {
|
||||
lib atomic.Pointer[content.Library]
|
||||
tmpls map[string]*template.Template
|
||||
defLocale string
|
||||
}
|
||||
|
||||
// New constructs a Server with the given library + default locale.
|
||||
func New(lib *content.Library, defaultLocale string) *Server {
|
||||
s := &Server{defLocale: defaultLocale, tmpls: make(map[string]*template.Template)}
|
||||
s.lib.Store(lib)
|
||||
|
||||
sub, err := fs.Sub(templatesFS, "templates")
|
||||
if err != nil {
|
||||
panic(fmt.Errorf("subFS templates: %w", err))
|
||||
}
|
||||
base := template.Must(template.New("base").Funcs(funcMap()).ParseFS(sub, "layout.html"))
|
||||
for _, name := range []string{"home.html", "category.html", "page.html"} {
|
||||
t := template.Must(base.Clone())
|
||||
template.Must(t.ParseFS(sub, name))
|
||||
s.tmpls[name] = t
|
||||
}
|
||||
return s
|
||||
}
|
||||
|
||||
// SwapLibrary replaces the active library atomically (used by SIGHUP reload).
|
||||
func (s *Server) SwapLibrary(lib *content.Library) { s.lib.Store(lib) }
|
||||
|
||||
func (s *Server) currentLib() *content.Library { return s.lib.Load() }
|
||||
|
||||
// Run starts the HTTP server and blocks until ctx is cancelled.
|
||||
func (s *Server) Run(ctx context.Context, addr string) error {
|
||||
mux := http.NewServeMux()
|
||||
mux.HandleFunc("GET /healthz", func(w http.ResponseWriter, _ *http.Request) {
|
||||
w.WriteHeader(http.StatusNoContent)
|
||||
})
|
||||
mux.HandleFunc("GET /search.json", s.handleSearch)
|
||||
mux.HandleFunc("GET /{$}", s.handleRoot)
|
||||
mux.HandleFunc("GET /{locale}/{$}", s.handleHome)
|
||||
mux.HandleFunc("GET /{locale}/{category}/{$}", s.handleCategory)
|
||||
mux.HandleFunc("GET /{locale}/{category}/{slug}", s.handlePage)
|
||||
|
||||
// /static/* is served BEFORE the mux to avoid pattern conflicts between
|
||||
// `/static/` and `/{locale}/{$}` (Go 1.22's mux can't pick a winner —
|
||||
// they overlap at exactly "/static/"). Wrapping order: securityHeaders
|
||||
// → staticFirst → mux.
|
||||
staticSub, err := fs.Sub(staticFS, "static")
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
staticFileHandler := http.StripPrefix("/static/", http.FileServerFS(staticSub))
|
||||
staticHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
// Zero-trust posture: only GET/HEAD, no directory listings, no dotfiles.
|
||||
if r.Method != http.MethodGet && r.Method != http.MethodHead {
|
||||
w.Header().Set("Allow", "GET, HEAD")
|
||||
http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
|
||||
return
|
||||
}
|
||||
path := r.URL.Path
|
||||
if strings.HasSuffix(path, "/") || strings.Contains(path, "/.") {
|
||||
http.NotFound(w, r)
|
||||
return
|
||||
}
|
||||
w.Header().Set("Cache-Control", "public, max-age=3600")
|
||||
staticFileHandler.ServeHTTP(w, r)
|
||||
})
|
||||
|
||||
root := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
if strings.HasPrefix(r.URL.Path, "/static/") {
|
||||
staticHandler.ServeHTTP(w, r)
|
||||
return
|
||||
}
|
||||
mux.ServeHTTP(w, r)
|
||||
})
|
||||
|
||||
srv := &http.Server{
|
||||
Addr: addr,
|
||||
Handler: securityHeaders(root),
|
||||
ReadHeaderTimeout: 10 * time.Second,
|
||||
ReadTimeout: 30 * time.Second,
|
||||
WriteTimeout: 60 * time.Second,
|
||||
IdleTimeout: 120 * time.Second,
|
||||
}
|
||||
|
||||
errCh := make(chan error, 1)
|
||||
go func() {
|
||||
slog.Info("listening", "addr", addr, "default_locale", s.defLocale)
|
||||
err := srv.ListenAndServe()
|
||||
if !errors.Is(err, http.ErrServerClosed) {
|
||||
errCh <- err
|
||||
return
|
||||
}
|
||||
errCh <- nil
|
||||
}()
|
||||
|
||||
select {
|
||||
case <-ctx.Done():
|
||||
shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
|
||||
defer cancel()
|
||||
_ = srv.Shutdown(shutdownCtx)
|
||||
return <-errCh
|
||||
case err := <-errCh:
|
||||
return err
|
||||
}
|
||||
}
|
||||
|
||||
// --- Handlers ---
|
||||
|
||||
func (s *Server) handleRoot(w http.ResponseWriter, r *http.Request) {
|
||||
http.Redirect(w, r, "/"+s.defLocale+"/", http.StatusFound)
|
||||
}
|
||||
|
||||
func (s *Server) handleHome(w http.ResponseWriter, r *http.Request) {
|
||||
locale := r.PathValue("locale")
|
||||
lib := s.currentLib()
|
||||
if !lib.HasLocale(locale) {
|
||||
http.NotFound(w, r)
|
||||
return
|
||||
}
|
||||
s.render(w, "home.html", map[string]any{
|
||||
"Locale": locale,
|
||||
"Locales": lib.Locales(),
|
||||
"Categories": lib.Categories(locale),
|
||||
"Path": []crumb{},
|
||||
})
|
||||
}
|
||||
|
||||
func (s *Server) handleCategory(w http.ResponseWriter, r *http.Request) {
|
||||
locale := r.PathValue("locale")
|
||||
categoryName := r.PathValue("category")
|
||||
lib := s.currentLib()
|
||||
if !lib.HasLocale(locale) {
|
||||
http.NotFound(w, r)
|
||||
return
|
||||
}
|
||||
var cat *content.Category
|
||||
for _, c := range lib.Categories(locale) {
|
||||
c := c
|
||||
if c.Name == categoryName {
|
||||
cat = &c
|
||||
break
|
||||
}
|
||||
}
|
||||
if cat == nil {
|
||||
http.NotFound(w, r)
|
||||
return
|
||||
}
|
||||
|
||||
var indexHTML template.HTML
|
||||
if cat.Index != nil {
|
||||
out, err := render.Markdown(cat.Index.Source)
|
||||
if err == nil {
|
||||
indexHTML = template.HTML(out)
|
||||
}
|
||||
}
|
||||
s.render(w, "category.html", map[string]any{
|
||||
"Locale": locale,
|
||||
"Locales": lib.Locales(),
|
||||
"Category": cat,
|
||||
"IndexHTML": indexHTML,
|
||||
"Path": []crumb{
|
||||
{Label: titleFor(cat), URL: "/" + locale + "/" + cat.Name + "/"},
|
||||
},
|
||||
})
|
||||
}
|
||||
|
||||
func (s *Server) handlePage(w http.ResponseWriter, r *http.Request) {
|
||||
locale := r.PathValue("locale")
|
||||
category := r.PathValue("category")
|
||||
slug := r.PathValue("slug")
|
||||
lib := s.currentLib()
|
||||
page := lib.Page(locale, category, slug)
|
||||
if page == nil {
|
||||
http.NotFound(w, r)
|
||||
return
|
||||
}
|
||||
html, err := render.Markdown(page.Source)
|
||||
if err != nil {
|
||||
http.Error(w, "render error", http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
s.render(w, "page.html", map[string]any{
|
||||
"Locale": locale,
|
||||
"Locales": lib.Locales(),
|
||||
"Page": page,
|
||||
"BodyHTML": template.HTML(html),
|
||||
"Path": []crumb{
|
||||
{Label: humanize(category), URL: "/" + locale + "/" + category + "/"},
|
||||
{Label: page.Title, URL: ""},
|
||||
},
|
||||
})
|
||||
}
|
||||
|
||||
// handleSearch returns a flat JSON array of {path, title, summary, body} for FlexSearch
|
||||
// to index in the browser. Body is plain markdown source — small enough for the page set.
|
||||
func (s *Server) handleSearch(w http.ResponseWriter, r *http.Request) {
|
||||
lang := r.URL.Query().Get("lang")
|
||||
if lang == "" {
|
||||
lang = s.defLocale
|
||||
}
|
||||
lib := s.currentLib()
|
||||
type entry struct {
|
||||
Path string `json:"path"`
|
||||
Title string `json:"title"`
|
||||
Summary string `json:"summary,omitempty"`
|
||||
Body string `json:"body"`
|
||||
}
|
||||
var out []entry
|
||||
for _, p := range lib.AllPages() {
|
||||
if p.Locale != lang || p.Slug == "_index" {
|
||||
continue
|
||||
}
|
||||
out = append(out, entry{
|
||||
Path: "/" + p.Path,
|
||||
Title: p.Title,
|
||||
Summary: p.Summary,
|
||||
Body: string(p.Source),
|
||||
})
|
||||
}
|
||||
w.Header().Set("Content-Type", "application/json; charset=utf-8")
|
||||
w.Header().Set("Cache-Control", "public, max-age=300")
|
||||
_ = json.NewEncoder(w).Encode(out)
|
||||
}
|
||||
|
||||
// --- Helpers ---
|
||||
|
||||
type crumb struct {
|
||||
Label string
|
||||
URL string // empty for the active leaf
|
||||
}
|
||||
|
||||
func (s *Server) render(w http.ResponseWriter, name string, data map[string]any) {
|
||||
t, ok := s.tmpls[name]
|
||||
if !ok {
|
||||
slog.Error("template not found", "name", name)
|
||||
http.Error(w, "template error", http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
w.Header().Set("Content-Type", "text/html; charset=utf-8")
|
||||
if err := t.ExecuteTemplate(w, "layout", data); err != nil {
|
||||
slog.Error("template render", "name", name, "err", err)
|
||||
}
|
||||
}
|
||||
|
||||
func titleFor(c *content.Category) string {
|
||||
if c.Index != nil {
|
||||
return c.Index.Title
|
||||
}
|
||||
return humanize(c.Name)
|
||||
}
|
||||
|
||||
func humanize(s string) string {
|
||||
s = strings.ReplaceAll(s, "-", " ")
|
||||
s = strings.ReplaceAll(s, "_", " ")
|
||||
if s == "" {
|
||||
return ""
|
||||
}
|
||||
return strings.ToUpper(s[:1]) + s[1:]
|
||||
}
|
||||
|
||||
func funcMap() template.FuncMap {
|
||||
return template.FuncMap{
|
||||
"humanize": humanize,
|
||||
}
|
||||
}
|
||||
|
||||
// securityHeaders adds the hardening headers expected for a public, no-auth,
|
||||
// internet-facing service. The intent is zero-trust: every visitor is anonymous
|
||||
// and untrusted, and the only data we serve is rendered markdown plus the static
|
||||
// CSS/JS bundle in /static/. Headers are tuned for that surface specifically.
|
||||
//
|
||||
// - CSP is tight: 'self' for default/script/style/connect; images from data: + https:.
|
||||
// 'unsafe-inline' is deliberately absent — templates have no inline styles or
|
||||
// scripts, and goldmark output (with WithUnsafe disabled) contains neither.
|
||||
// - HSTS is set assuming TLS termination upstream (k8s ingress).
|
||||
// - COOP/CORP isolate the document from cross-origin actors.
|
||||
// - Permissions-Policy disables every browser capability we don't use.
|
||||
func securityHeaders(next http.Handler) http.Handler {
|
||||
const csp = "default-src 'self'; " +
|
||||
"img-src 'self' data: https:; " +
|
||||
"style-src 'self'; " +
|
||||
"script-src 'self'; " +
|
||||
"connect-src 'self'; " +
|
||||
"object-src 'none'; " +
|
||||
"base-uri 'self'; " +
|
||||
"form-action 'self'; " +
|
||||
"frame-ancestors 'none'"
|
||||
const permissionsPolicy = "accelerometer=(), camera=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), payment=(), usb=()"
|
||||
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
h := w.Header()
|
||||
h.Set("X-Content-Type-Options", "nosniff")
|
||||
h.Set("X-Frame-Options", "DENY")
|
||||
h.Set("Referrer-Policy", "no-referrer")
|
||||
h.Set("Strict-Transport-Security", "max-age=31536000; includeSubDomains")
|
||||
h.Set("Cross-Origin-Opener-Policy", "same-origin")
|
||||
h.Set("Cross-Origin-Resource-Policy", "same-origin")
|
||||
h.Set("Content-Security-Policy", csp)
|
||||
h.Set("Permissions-Policy", permissionsPolicy)
|
||||
next.ServeHTTP(w, r)
|
||||
})
|
||||
}
|
||||
@@ -0,0 +1,71 @@
|
||||
// search.js — minimal client-side search.
|
||||
// Loads /search.json?lang=<locale>, builds an in-memory index, renders results
|
||||
// as the user types in the header search box.
|
||||
//
|
||||
// Deliberately tiny — no FlexSearch dependency yet (the page set is small,
|
||||
// linear scan with case-insensitive substring is plenty). Swap in FlexSearch
|
||||
// or Lunr if the corpus grows past a few hundred pages.
|
||||
(function () {
|
||||
const input = document.getElementById('search-input');
|
||||
const results = document.getElementById('search-results');
|
||||
if (!input || !results) return;
|
||||
|
||||
const lang = document.documentElement.lang || 'en';
|
||||
let pages = [];
|
||||
let loaded = false;
|
||||
|
||||
function loadIndex() {
|
||||
if (loaded) return Promise.resolve();
|
||||
return fetch('/search.json?lang=' + encodeURIComponent(lang))
|
||||
.then(r => r.json())
|
||||
.then(data => { pages = data || []; loaded = true; })
|
||||
.catch(() => { /* silent — search just stays empty */ });
|
||||
}
|
||||
|
||||
function escapeHtml(s) {
|
||||
return String(s).replace(/[&<>"']/g, c => ({'&':'&','<':'<','>':'>','"':'"',"'":'''}[c]));
|
||||
}
|
||||
|
||||
function search(q) {
|
||||
if (!q || q.length < 2) return [];
|
||||
const needle = q.toLowerCase();
|
||||
const out = [];
|
||||
for (const p of pages) {
|
||||
const titleHit = p.title && p.title.toLowerCase().includes(needle);
|
||||
const summaryHit = p.summary && p.summary.toLowerCase().includes(needle);
|
||||
const bodyHit = p.body && p.body.toLowerCase().includes(needle);
|
||||
if (titleHit || summaryHit || bodyHit) {
|
||||
// crude scoring: title > summary > body
|
||||
const score = (titleHit ? 100 : 0) + (summaryHit ? 10 : 0) + (bodyHit ? 1 : 0);
|
||||
out.push({ ...p, score });
|
||||
}
|
||||
if (out.length >= 50) break;
|
||||
}
|
||||
out.sort((a, b) => b.score - a.score);
|
||||
return out.slice(0, 8);
|
||||
}
|
||||
|
||||
function render(matches) {
|
||||
if (!matches.length) { results.hidden = true; results.innerHTML = ''; return; }
|
||||
results.innerHTML = matches.map(m =>
|
||||
`<li><a href="${escapeHtml(m.path)}">
|
||||
<span class="title">${escapeHtml(m.title)}</span>
|
||||
${m.summary ? `<span class="summary">${escapeHtml(m.summary)}</span>` : ''}
|
||||
</a></li>`
|
||||
).join('');
|
||||
results.hidden = false;
|
||||
}
|
||||
|
||||
let timer = null;
|
||||
input.addEventListener('focus', loadIndex);
|
||||
input.addEventListener('input', () => {
|
||||
clearTimeout(timer);
|
||||
timer = setTimeout(() => {
|
||||
loadIndex().then(() => render(search(input.value.trim())));
|
||||
}, 80);
|
||||
});
|
||||
input.addEventListener('blur', () => {
|
||||
// Delay so click on a result registers before hiding.
|
||||
setTimeout(() => { results.hidden = true; }, 150);
|
||||
});
|
||||
})();
|
||||
@@ -0,0 +1,152 @@
|
||||
/* automc-tutorials — minimal opinionated CSS, no framework. */
|
||||
* { box-sizing: border-box; }
|
||||
html { font: 16px/1.55 system-ui, -apple-system, "Segoe UI", Roboto, sans-serif; color: #222; background: #fff; }
|
||||
body { margin: 0; }
|
||||
a { color: #2c5fa3; text-decoration: none; }
|
||||
a:hover { text-decoration: underline; }
|
||||
|
||||
.site-header {
|
||||
display: flex; align-items: center; gap: 1rem;
|
||||
padding: 0.75rem 1.25rem;
|
||||
border-bottom: 1px solid #e5e5e5;
|
||||
background: #fafafa;
|
||||
position: sticky; top: 0; z-index: 10;
|
||||
}
|
||||
.brand { font-weight: 700; font-size: 1.05rem; color: #222; }
|
||||
.brand:hover { text-decoration: none; }
|
||||
|
||||
.search { position: relative; flex: 1; max-width: 28rem; }
|
||||
.search input {
|
||||
width: 100%; padding: 0.4rem 0.6rem;
|
||||
border: 1px solid #ccc; border-radius: 6px;
|
||||
font: inherit;
|
||||
}
|
||||
#search-results {
|
||||
position: absolute; top: 100%; left: 0; right: 0;
|
||||
margin: 0.25rem 0 0; padding: 0; list-style: none;
|
||||
background: #fff; border: 1px solid #ddd; border-radius: 6px;
|
||||
max-height: 18rem; overflow-y: auto;
|
||||
box-shadow: 0 4px 12px rgba(0,0,0,0.08);
|
||||
}
|
||||
#search-results li { padding: 0; }
|
||||
#search-results a {
|
||||
display: block; padding: 0.5rem 0.75rem;
|
||||
border-bottom: 1px solid #f0f0f0;
|
||||
color: #222;
|
||||
}
|
||||
#search-results a:hover { background: #f4f7fb; text-decoration: none; }
|
||||
#search-results .title { font-weight: 600; }
|
||||
#search-results .summary { display: block; font-size: 0.85rem; color: #666; }
|
||||
|
||||
.locale-switch a.lang {
|
||||
display: inline-block;
|
||||
padding: 0.25rem 0.5rem;
|
||||
margin-left: 0.25rem;
|
||||
border-radius: 4px;
|
||||
text-transform: uppercase;
|
||||
font-size: 0.8rem;
|
||||
color: #555;
|
||||
}
|
||||
.locale-switch a.lang.active { background: #2c5fa3; color: #fff; }
|
||||
|
||||
.breadcrumbs {
|
||||
padding: 0.5rem 1.25rem;
|
||||
font-size: 0.9rem; color: #666;
|
||||
border-bottom: 1px solid #f0f0f0;
|
||||
}
|
||||
.breadcrumbs .sep { margin: 0 0.4rem; color: #aaa; }
|
||||
.breadcrumbs .active { color: #222; }
|
||||
|
||||
main {
|
||||
max-width: 50rem;
|
||||
margin: 0 auto;
|
||||
padding: 2rem 1.25rem;
|
||||
}
|
||||
|
||||
h1 { font-size: 1.75rem; margin: 0 0 0.5rem; }
|
||||
h2 { font-size: 1.35rem; margin: 1.5rem 0 0.5rem; }
|
||||
.lead { font-size: 1.1rem; color: #555; margin: 0.5rem 0 1.5rem; }
|
||||
|
||||
.category-list { list-style: none; padding: 0; display: grid; gap: 1rem; }
|
||||
.category-item a {
|
||||
display: block;
|
||||
padding: 1rem 1.25rem;
|
||||
border: 1px solid #e0e0e0;
|
||||
border-radius: 8px;
|
||||
color: #222;
|
||||
transition: border-color 0.15s, box-shadow 0.15s;
|
||||
}
|
||||
.category-item a:hover {
|
||||
border-color: #2c5fa3;
|
||||
box-shadow: 0 2px 8px rgba(44,95,163,0.1);
|
||||
text-decoration: none;
|
||||
}
|
||||
.category-item h2 { margin: 0 0 0.25rem; font-size: 1.15rem; }
|
||||
.category-item p { margin: 0.25rem 0; color: #555; }
|
||||
.category-item .page-count { font-size: 0.85rem; color: #888; }
|
||||
|
||||
.page-list { list-style: none; padding: 0; }
|
||||
.page-list li { margin-bottom: 0.5rem; }
|
||||
.page-list a {
|
||||
display: block;
|
||||
padding: 0.6rem 0.8rem;
|
||||
border-left: 3px solid transparent;
|
||||
border-radius: 4px;
|
||||
}
|
||||
.page-list a:hover { border-left-color: #2c5fa3; background: #f7f9fc; text-decoration: none; }
|
||||
.page-list strong { color: #222; }
|
||||
.page-list .summary { display: block; font-size: 0.9rem; color: #666; margin-top: 0.15rem; }
|
||||
|
||||
.page-header { margin-bottom: 1.5rem; }
|
||||
.page-header .summary { color: #555; font-size: 1.05rem; }
|
||||
|
||||
.prose { line-height: 1.7; }
|
||||
.prose code {
|
||||
background: #f4f4f5; padding: 0.1rem 0.35rem; border-radius: 3px;
|
||||
font-size: 0.9em; font-family: ui-monospace, "SF Mono", Menlo, monospace;
|
||||
}
|
||||
.prose pre {
|
||||
background: #1e1e2e; color: #cdd6f4;
|
||||
padding: 1rem; border-radius: 8px; overflow-x: auto;
|
||||
font-size: 0.9rem; line-height: 1.5;
|
||||
}
|
||||
.prose pre code { background: transparent; padding: 0; color: inherit; }
|
||||
.prose img { max-width: 100%; border-radius: 8px; }
|
||||
.prose blockquote {
|
||||
border-left: 4px solid #2c5fa3;
|
||||
margin: 1rem 0; padding: 0.5rem 1rem;
|
||||
background: #f7f9fc;
|
||||
}
|
||||
.prose table { border-collapse: collapse; width: 100%; margin: 1rem 0; }
|
||||
.prose th, .prose td { border: 1px solid #e0e0e0; padding: 0.5rem 0.75rem; text-align: left; }
|
||||
.prose th { background: #fafafa; }
|
||||
|
||||
.site-footer {
|
||||
margin-top: 4rem;
|
||||
padding: 1.5rem 1.25rem;
|
||||
border-top: 1px solid #e5e5e5;
|
||||
text-align: center;
|
||||
font-size: 0.85rem;
|
||||
color: #888;
|
||||
}
|
||||
|
||||
@media (prefers-color-scheme: dark) {
|
||||
html { color: #ddd; background: #1a1a1a; }
|
||||
.site-header { background: #222; border-color: #333; }
|
||||
.brand { color: #ddd; }
|
||||
a { color: #6aa2dc; }
|
||||
.search input { background: #2a2a2a; border-color: #444; color: #ddd; }
|
||||
#search-results { background: #222; border-color: #444; }
|
||||
#search-results a { color: #ddd; border-color: #2f2f2f; }
|
||||
#search-results a:hover { background: #2a2f3a; }
|
||||
.breadcrumbs { color: #999; border-color: #333; }
|
||||
.breadcrumbs .active { color: #eee; }
|
||||
.category-item a { background: #222; border-color: #333; color: #ddd; }
|
||||
.category-item a:hover { border-color: #6aa2dc; }
|
||||
.page-list a:hover { background: #2a2a2a; }
|
||||
.prose code { background: #2a2a2a; color: #f4f4f5; }
|
||||
.prose blockquote { background: #222; }
|
||||
.prose th { background: #222; }
|
||||
.prose th, .prose td { border-color: #333; }
|
||||
.site-footer { border-color: #333; color: #777; }
|
||||
}
|
||||
@@ -0,0 +1,18 @@
|
||||
{{define "title"}}{{if .Category.Index}}{{.Category.Index.Title}}{{else}}{{humanize .Category.Name}}{{end}} · automc tutorials{{end}}
|
||||
{{define "content"}}
|
||||
<article class="category">
|
||||
<h1>{{if .Category.Index}}{{.Category.Index.Title}}{{else}}{{humanize .Category.Name}}{{end}}</h1>
|
||||
{{with .IndexHTML}}<div class="prose">{{.}}</div>{{end}}
|
||||
|
||||
<ul class="page-list">
|
||||
{{range .Category.Pages}}
|
||||
<li>
|
||||
<a href="/{{$.Locale}}/{{.Category}}/{{.Slug}}">
|
||||
<strong>{{.Title}}</strong>
|
||||
{{with .Summary}}<span class="summary">{{.}}</span>{{end}}
|
||||
</a>
|
||||
</li>
|
||||
{{end}}
|
||||
</ul>
|
||||
</article>
|
||||
{{end}}
|
||||
@@ -0,0 +1,17 @@
|
||||
{{define "title"}}automc tutorials{{end}}
|
||||
{{define "content"}}
|
||||
<h1>Tutorials</h1>
|
||||
<p class="lead">Pick a topic. New here? Start with <strong>install client</strong>, then <strong>register</strong>.</p>
|
||||
|
||||
<ul class="category-list">
|
||||
{{range .Categories}}
|
||||
<li class="category-item">
|
||||
<a href="/{{$.Locale}}/{{.Name}}/">
|
||||
<h2>{{if .Index}}{{.Index.Title}}{{else}}{{humanize .Name}}{{end}}</h2>
|
||||
{{with .Index}}{{with .Summary}}<p>{{.}}</p>{{end}}{{end}}
|
||||
<span class="page-count">{{len .Pages}} page{{if ne (len .Pages) 1}}s{{end}}</span>
|
||||
</a>
|
||||
</li>
|
||||
{{end}}
|
||||
</ul>
|
||||
{{end}}
|
||||
@@ -0,0 +1,43 @@
|
||||
{{define "layout"}}<!doctype html>
|
||||
<html lang="{{.Locale}}">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>{{block "title" .}}automc tutorials{{end}}</title>
|
||||
<link rel="stylesheet" href="/static/style.css">
|
||||
</head>
|
||||
<body>
|
||||
<header class="site-header">
|
||||
<a class="brand" href="/{{.Locale}}/">automc tutorials</a>
|
||||
<div class="search">
|
||||
<input type="search" id="search-input" placeholder="Search..." autocomplete="off">
|
||||
<ul id="search-results" hidden></ul>
|
||||
</div>
|
||||
<nav class="locale-switch">
|
||||
{{range .Locales}}
|
||||
<a href="/{{.}}/" class="lang {{if eq . $.Locale}}active{{end}}">{{.}}</a>
|
||||
{{end}}
|
||||
</nav>
|
||||
</header>
|
||||
|
||||
{{with .Path}}
|
||||
<nav class="breadcrumbs">
|
||||
<a href="/{{$.Locale}}/">home</a>
|
||||
{{range .}}
|
||||
<span class="sep">›</span>
|
||||
{{if .URL}}<a href="{{.URL}}">{{.Label}}</a>{{else}}<span class="active">{{.Label}}</span>{{end}}
|
||||
{{end}}
|
||||
</nav>
|
||||
{{end}}
|
||||
|
||||
<main>
|
||||
{{block "content" .}}{{end}}
|
||||
</main>
|
||||
|
||||
<footer class="site-footer">
|
||||
<span>automc-tutorials · <a href="https://git.timemachine.center/Timemachine/automc-tutorials">source</a></span>
|
||||
</footer>
|
||||
|
||||
<script src="/static/search.js" defer></script>
|
||||
</body>
|
||||
</html>{{end}}
|
||||
@@ -0,0 +1,10 @@
|
||||
{{define "title"}}{{.Page.Title}} · automc tutorials{{end}}
|
||||
{{define "content"}}
|
||||
<article class="page">
|
||||
<header class="page-header">
|
||||
<h1>{{.Page.Title}}</h1>
|
||||
{{with .Page.Summary}}<p class="summary">{{.}}</p>{{end}}
|
||||
</header>
|
||||
<div class="prose">{{.BodyHTML}}</div>
|
||||
</article>
|
||||
{{end}}
|
||||
Reference in New Issue
Block a user