khosra/internal/render/theme.go

// Building the theme: the embedded reference templates, the site's overlay of them, and the stylesheet.
//
// Split from render.go when that file reached the length advisory (conventions.md). Parsing a theme and
// rendering with one are two topics: this file runs once per rebuild, the other runs per request.
package render

import (
	"embed"
	"fmt"
	"html/template"
	"io/fs"
)

//go:embed templates
var themeFS embed.FS

// parsedTheme is the sets a request executes, and the stylesheet the shell inlines.
type parsedTheme struct {
	// Two sets, not one: base plus the block that kind of page defines. A single set would have two
	// definitions of "main" fighting, which is why per-type sets are the shape (ADR-0019).
	page *template.Template
	list *template.Template
	// partials are named fragments a feature renders through, so no feature decides markup (ADR-0036).
	partials *template.Template
	// extras is the set for a bundle's supporting-file listing.
	extras *template.Template
	style  template.CSS
}

// parseTheme parses every set the theme is made of, plus its stylesheet.
//
// Its own function because a running server parses the theme again on every rebuild (ADR-0055): startup and
// reparse must be the same code, or the theme a running site serves drifts from the one a fresh boot would.
func parseTheme(siteFS fs.FS) (*parsedTheme, error) {
	page, err := parseSet(siteFS, "templates/base.html", "templates/page.html")
	if err != nil {
		return nil, fmt.Errorf("bundle templates: %w", err)
	}
	list, err := parseSet(siteFS, "templates/base.html", "templates/list.html")
	if err != nil {
		return nil, fmt.Errorf("listing templates: %w", err)
	}
	partials, err := parseSet(siteFS, "templates/shortcodes.html", "templates/shortcodes/*.html")
	if err != nil {
		return nil, fmt.Errorf("partial templates: %w", err)
	}
	extras, err := parseSet(siteFS, "templates/base.html", "templates/extras.html")
	if err != nil {
		return nil, fmt.Errorf("extras templates: %w", err)
	}
	css, err := readStyle(siteFS)
	if err != nil {
		return nil, err
	}
	return &parsedTheme{page: page, list: list, partials: partials, extras: extras, style: css}, nil
}

// parseSet builds one set from the named embedded templates, then the site's versions of exactly those
// files parsed after them.
//
// Parse order is the whole mechanism — the last definition of a name wins — so a site redefines one
// named block and inherits the rest (ADR-0019). Only the files this set is built from are overlaid:
// overlaying every site template into every set would let a listing's "main" leak into bundle pages,
// which is the collision per-kind sets exist to prevent.
func parseSet(siteFS fs.FS, names ...string) (*template.Template, error) {
	// Funcs are attached before anything is parsed, so the chrome helpers are available to a site
	// override's blocks as well as the embedded ones (ADR-0034). A name may be a glob, which is how a
	// directory of fragments is parsed after the single file it may replace (ADR-0071).
	set, parsed := template.New("theme").Funcs(funcs), false
	for _, from := range []fs.FS{themeFS, siteFS} {
		if from == nil {
			continue
		}
		for _, name := range names {
			if matches, _ := fs.Glob(from, name); len(matches) == 0 {
				continue
			}
			var err error
			if set, err = set.ParseFS(from, name); err != nil {
				return nil, fmt.Errorf("parse %s: %w", name, err)
			}
			parsed = true
		}
	}
	// Nothing matched anywhere, which means a name the binary embeds has been renamed. A startup failure,
	// because the alternative is an empty set and a template error on the first request.
	if !parsed {
		return nil, fmt.Errorf("no template matched %v", names)
	}
	return set, nil
}

// readStyle prefers the site's stylesheet and falls back to the reference one.
func readStyle(siteFS fs.FS) (template.CSS, error) {
	if siteFS != nil {
		if data, err := fs.ReadFile(siteFS, "templates/theme.css"); err == nil {
			return template.CSS(data), nil
		}
	}
	data, err := themeFS.ReadFile("templates/theme.css")
	if err != nil {
		return "", fmt.Errorf("read reference stylesheet: %w", err)
	}
	return template.CSS(data), nil
}