jeduden
diff --git a/‎docs/development/website-config.md‎
Lines changed: 95 additions & 0 deletions b/‎docs/development/website-config.md‎
Lines changed: 95 additions & 0 deletions
diff --git a/‎internal/release/template_summary_test.go‎
Lines changed: 73 additions & 0 deletions b/‎internal/release/template_summary_test.go‎
Lines changed: 73 additions & 0 deletions
@@ -99,3 +99,98 @@ Tracked by `mdsmith-release sync-messaging` from the
 [`docs/brand/messaging.md`](../brand/messaging.md). Hand-edits
 to this field are reverted on the next sync. To change the
 text, edit the source file and run the sync.
+
+## Summary front-matter rendering
+
+Each docs page carries a `summary` front-matter field.
+The field holds inline Markdown. Templates render it
+through Hugo's `.RenderString` so backticks become
+`<code>` and `[text](url)` becomes `<a>`.
+
+The classifier lives in
+[`internal/templatecheck`][tpl-check]. It exports
+`Scan(path, content)`. The function parses each
+template with Go's `text/template/parse` package.
+`SkipFuncCheck` mode is set so undefined Hugo
+helpers do not error. The walker then visits the AST
+and classifies each `.Params.summary` reference by
+node context.
+
+The integration test in
+[`internal/release/template_summary_test.go`][tpl-test]
+walks `website/layouts/**/*.html` and calls
+`templatecheck.Scan` on each file. No regex
+tokenising. No exemption list. Comments, string
+literals, and CRLF line endings are handled by the
+parser.
+
+Safe forms:
+
+- A presence predicate — `{{ if .Params.summary }}`,
+  the negated form, compound shapes
+  (`{{ if and .Params.summary .X }}`,
+  `{{ if or .Params.summary .Other }}`), the `else if`
+  variant, subfield access
+  (`{{ if .Params.summary.HTML }}`), or any other
+  comparison that does not produce output.
+- A `.RenderString` call with the summary as a
+  positional argument:
+  `{{ .RenderString (dict "display" "inline") .Params.summary }}`.
+  Qualified receivers (`.Page.RenderString`,
+  `$.RenderString`) are recognised.
+- A pipeline that passes the summary through
+  `.RenderString` and then any number of post-render
+  filters: `{{ .Params.summary | .RenderString }}`,
+  `{{ .Params.summary | strings.TrimSpace | .RenderString }}`,
+  `{{ $.RenderString (dict "display" "inline") .Params.summary | plainify }}`.
+  Once the value has rendered, downstream stages such
+  as `plainify` or `safeHTML` are fine.
+- A sub-pipeline argument whose output feeds
+  `.RenderString`:
+  `{{ .RenderString (dict) (printf "wrapper: %s" .Params.summary) }}`.
+
+Forbidden forms:
+
+- `{{ with .Params.summary }}` and
+  `{{ else with .Params.summary }}` — these rebind
+  `.` to the summary string and the body typically
+  emits the value raw.
+- `{{ range .Params.summary }}` — ranging over a
+  string iterates rune-by-rune and emits each code
+  point as an integer.
+- `{{ template "name" .Params.summary }}` and
+  `{{ block "name" .Params.summary }}` — these pass
+  the summary as the sub-template's dot. The
+  sub-template lives in a separate parse tree; the
+  scanner cannot follow the rebinding across the
+  boundary.
+- The bare `{{ .Params.summary }}` action.
+- Variable assignment in any context — `{{ $s := .Params.summary }}`,
+  `{{ if $s := .Params.summary }}`,
+  `{{ range $i, $v := .Params.summary }}`. The bound
+  name escapes the per-action check.
+- `.Params.summary` referenced in a value-emitting
+  action whose pipe does not reach `.RenderString`:
+  `{{ printf "%s" .Params.summary }}`,
+  `{{ .Params.summary | print "x" .Page.RenderString }}`
+  (the second example references `.RenderString` as
+  a value passed to `print`, not as a method call).
+
+`baseof.html` reuses the same projection. Each
+branch of its meta-description chain runs the
+source value through `$.RenderString` then
+`plainify`. The sources are `.Description`,
+`.Params.summary`, `.Params.description`, and
+`.Site.Params.description`. Meta content cannot
+carry HTML. Backticks become `<code>` then plain
+text. SEO snippets see clean prose.
+
+The rule applies only to `.Params.summary` today. If
+other front-matter scalars (e.g. `lead`, `eyebrow`,
+`tagline`) gain inline-Markdown content in the future,
+extend the AST classifier in
+[`internal/templatecheck`][tpl-check] to accept the
+new field name set.
+
+[tpl-check]: ../../internal/templatecheck/templatecheck.go
+[tpl-test]: ../../internal/release/template_summary_test.go
@@ -0,0 +1,73 @@
+package release
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/jeduden/mdsmith/internal/templatecheck"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestSummaryFrontMatterRenderedThroughRenderString walks every
+// `.html` file under `website/layouts/` and asserts none uses
+// `.Params.summary` in a forbidden context. The classifier lives
+// in `internal/templatecheck`; this is the integration test that
+// applies it to the real layouts. No template is exempt —
+// baseof.html's meta-description fallback uses
+// `{{ if .Params.summary }}{{ $.RenderString ... .Params.summary | plainify }}`
+// (no `with`-rebinding) so the scanner verifies it natively.
+//
+// See docs/development/website-config.md for the safe/forbidden
+// shape enumeration and `internal/templatecheck/templatecheck.go`
+// for the scanner implementation.
+func TestSummaryFrontMatterRenderedThroughRenderString(t *testing.T) {
+	layoutsDir := filepath.Join(repoRoot(t), "website", "layouts")
+
+	var violations []templatecheck.Violation
+	var ioErrors []string
+	scanned := 0
+	require.NoError(t, filepath.Walk(layoutsDir, func(path string, info os.FileInfo, err error) error {
+		if err != nil {
+			ioErrors = append(ioErrors, fmt.Sprintf("walk %s: %v", path, err))
+			return nil
+		}
+		if info.IsDir() || filepath.Ext(path) != ".html" {
+			return nil
+		}
+		rel, relErr := filepath.Rel(layoutsDir, path)
+		if relErr != nil {
+			ioErrors = append(ioErrors, fmt.Sprintf("rel %s: %v", path, relErr))
+			return nil
+		}
+		data, readErr := os.ReadFile(path)
+		if readErr != nil {
+			ioErrors = append(ioErrors, fmt.Sprintf("read %s: %v", path, readErr))
+			return nil
+		}
+		got, scanErr := templatecheck.Scan(rel, string(data))
+		if scanErr != nil {
+			ioErrors = append(ioErrors, fmt.Sprintf("scan %s: %v", path, scanErr))
+			return nil
+		}
+		violations = append(violations, got...)
+		scanned++
+		return nil
+	}))
+
+	formatted := make([]string, 0, len(violations))
+	for _, v := range violations {
+		formatted = append(formatted, fmt.Sprintf("%s:%d: %s", v.Path, v.Line, v.Why))
+	}
+	assert.Empty(t, formatted, "summary front-matter rendering violations")
+	assert.Empty(t, ioErrors, "filesystem errors during scan")
+	// Guard against the test passing vacuously if website/layouts/
+	// ever disappears or the walker is misconfigured. The tree
+	// currently holds 24 .html files (_default/, partials/,
+	// shortcodes/, _markup/, rule/, index.html); set the floor at
+	// 20 to catch a catastrophic regression while leaving headroom
+	// for legitimate template cleanup.
+	assert.GreaterOrEqual(t, scanned, 20, "expected to scan at least 20 .html files; got %d", scanned)
+}