resources/page: Deprecate .Sites.First in favor of .Sites.Default

Closes #12513

3 files changed, 54 insertions, 3 deletions

diff --git a/hugolib/pages_language_merge_test.go b/hugolib/pages_language_merge_test.go
index 8a5d6c184..3862d7cf0 100644
--- a/hugolib/pages_language_merge_test.go
+++ b/hugolib/pages_language_merge_test.go
@@ -68,7 +68,7 @@ func TestMergeLanguages(t *testing.T) {
 
 	firstNN := nnSite.RegularPages()[0]
 	c.Assert(len(firstNN.Sites()), qt.Equals, 4)
-	c.Assert(firstNN.Sites().First().Language().Lang, qt.Equals, "en")
+	c.Assert(firstNN.Sites().Default().Language().Lang, qt.Equals, "en")
 
 	nnBundle := nnSite.getPageOldVersion("page", "bundle")
 	enBundle := enSite.getPageOldVersion("page", "bundle")
diff --git a/resources/page/site.go b/resources/page/site.go
index df33485eb..56f438cb6 100644
--- a/resources/page/site.go
+++ b/resources/page/site.go
@@ -139,8 +139,15 @@ type Site interface {
 // Sites represents an ordered list of sites (languages).
 type Sites []Site
 
-// First is a convenience method to get the first Site, i.e. the main language.
+// Deprecated: Use .Sites.Default instead.
 func (s Sites) First() Site {
+	hugo.Deprecate(".Sites.First", "Use .Sites.Default instead.", "v0.127.0")
+	return s.Default()
+}
+
+// Default is a convenience method to get the site corresponding to the default
+// content language.
+func (s Sites) Default() Site {
 	if len(s) == 0 {
 		return nil
 	}
@@ -165,7 +172,7 @@ func (s *siteWrapper) Key() string {
 	return s.s.Language().Lang
 }
 
-// // Deprecated: Use .Site.Params instead.
+// Deprecated: Use .Site.Params instead.
 func (s *siteWrapper) Social() map[string]string {
 	return s.s.Social()
 }
diff --git a/resources/page/site_integration_test.go b/resources/page/site_integration_test.go
new file mode 100644
index 000000000..60064df3a
--- /dev/null
+++ b/resources/page/site_integration_test.go
@@ -0,0 +1,44 @@
+// Copyright 2024 The Hugo Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package page_test
+
+import (
+	"testing"
+
+	"github.com/gohugoio/hugo/hugolib"
+)
+
+// Issue 12513
+func TestPageSiteSitesDefault(t *testing.T) {
+	t.Parallel()
+
+	files := `
+-- hugo.toml --
+disableKinds = ['page','rss','section','sitemap','taxonomy','term']
+defaultContentLanguage = 'de'
+defaultContentLanguageInSubdir = true
+[languages.en]
+languageName = 'English'
+weight = 1
+[languages.de]
+languageName = 'Deutsch'
+weight = 2
+-- layouts/index.html --
+{{ .Site.Sites.Default.Language.LanguageName }}
+`
+
+	b := hugolib.Test(t, files)
+
+	b.AssertFileContent("public/de/index.html", "Deutsch")
+}