Handle build vs _build in front matter

* Throw a detailed error message in the mentioned case
* Also fixed a dropped error

Fixes #11970

3 files changed, 46 insertions, 5 deletions

diff --git a/hugolib/content_map_page.go b/hugolib/content_map_page.go
index 9accd190e..27b37a8fc 100644
--- a/hugolib/content_map_page.go
+++ b/hugolib/content_map_page.go
@@ -1239,7 +1239,9 @@ func (sa *sitePagesAssembler) applyAggregates() error {
 		}
 
 		// Combine the cascade map with front matter.
-		pageBundle.setMetaPost(cascade)
+		if err := pageBundle.setMetaPost(cascade); err != nil {
+			return false, err
+		}
 
 		// We receive cascade values from above. If this leads to a change compared
 		// to the previous value, we need to mark the page and its dependencies as changed.
@@ -1304,7 +1306,9 @@ func (sa *sitePagesAssembler) applyAggregates() error {
 				if data != nil {
 					cascade = data.(map[page.PageMatcher]maps.Params)
 				}
-				pageResource.setMetaPost(cascade)
+				if err := pageResource.setMetaPost(cascade); err != nil {
+					return false, err
+				}
 			}
 
 			return false, nil
@@ -1369,7 +1373,9 @@ func (sa *sitePagesAssembler) applyAggregatesToTaxonomiesAndTerms() error {
 					if data != nil {
 						cascade = data.(map[page.PageMatcher]maps.Params)
 					}
-					p.setMetaPost(cascade)
+					if err := p.setMetaPost(cascade); err != nil {
+						return false, err
+					}
 
 					if err := sa.pageMap.treeTaxonomyEntries.WalkPrefix(
 						doctree.LockTypeRead,
diff --git a/hugolib/page__meta.go b/hugolib/page__meta.go
index b19a82fde..35b7766b6 100644
--- a/hugolib/page__meta.go
+++ b/hugolib/page__meta.go
@@ -428,15 +428,29 @@ func (p *pageState) setMetaPostParams() error {
 	}
 
 	var buildConfig any
+	var isNewBuildKeyword bool
 	if v, ok := pm.pageConfig.Params["_build"]; ok {
 		buildConfig = v
 	} else {
 		buildConfig = pm.pageConfig.Params["build"]
+		isNewBuildKeyword = true
 	}
-
 	pm.pageConfig.Build, err = pagemeta.DecodeBuildConfig(buildConfig)
 	if err != nil {
-		return err
+		//lint:ignore ST1005 end user message.
+		var msgDetail string
+		if isNewBuildKeyword {
+			msgDetail = `. We renamed the _build keyword to build in Hugo 0.123.0. We recommend putting user defined params in the params section, e.g.:
+---
+title: "My Title"
+params:
+  build: "My Build"
+---
+´   
+
+`
+		}
+		return fmt.Errorf("failed to decode build config in front matter: %s%s", err, msgDetail)
 	}
 
 	var sitemapSet bool
diff --git a/hugolib/params_test.go b/hugolib/params_test.go
index 6f890b43b..cbcc8e540 100644
--- a/hugolib/params_test.go
+++ b/hugolib/params_test.go
@@ -181,3 +181,24 @@ lang = 'nn'
 	b, err := TestE(t, files)
 	b.Assert(err, qt.IsNotNil)
 }
+
+// Issue 11970.
+func TestFrontMatterBuildIsHugoKeyword(t *testing.T) {
+	t.Parallel()
+
+	files := `
+-- hugo.toml --
+baseURL = "https://example.org/"
+-- content/p1.md --
+---
+title: "P1"
+build: "foo"
+---
+-- layouts/_default/single.html --
+Params: {{ range $k, $v := .Params }}{{ $k }}: {{ $v }}|{{ end }}$
+`
+	b, err := TestE(t, files)
+
+	b.Assert(err, qt.IsNotNil)
+	b.Assert(err.Error(), qt.Contains, "We renamed the _build keyword")
+}