hugolib: Add parameter option for .Summary

Add the ability to have a `summary` page variable that overrides
the auto-generated summary.  Logic for obtaining summary becomes:

  * if summary divider is present in content use the text above it
  * if summary variables is present in page metadata use that
  * auto-generate summary from first _x_ words of the content

Fixes gohugoio#5800

hugolib/page__meta.go

@@ -63,6 +63,8 @@ type pageMeta struct {
 	title     string
 	linkTitle string
 
+	summary string
+
 	resourcePath string
 
 	weight int
@@ -360,6 +362,9 @@ func (pm *pageMeta) setMetadata(p *pageState, frontmatter map[string]interface{}
 		case "linktitle":
 			pm.linkTitle = cast.ToString(v)
 			pm.params[loki] = pm.linkTitle
+		case "summary":
+			pm.summary = cast.ToString(v)
+			pm.params[loki] = pm.summary
 		case "description":
 			pm.description = cast.ToString(v)
 			pm.params[loki] = pm.description

hugolib/page__per_output.go

@@ -128,6 +128,17 @@ func newPageContentOutput(p *pageState) func(f output.Format) (*pageContentOutpu
 							cp.summary = helpers.BytesToHTML(summary)
 						}
 					}
+				} else if cp.p.m.summary != "" {
+					html := cp.p.s.ContentSpec.RenderBytes(&helpers.RenderingContext{
+						Content: []byte(cp.p.m.summary), RenderTOC: false, PageFmt: cp.p.m.markup,
+						Cfg:        p.Language(),
+						DocumentID: p.File().UniqueID(), DocumentName: p.File().Path(),
+						Config: cp.p.getRenderingConfig()})
+					// Strip enclosing <p>
+					html = []byte(strings.TrimSpace(string(html)))
+					html = []byte(strings.TrimPrefix(string(html), "<p>"))
+					html = []byte(strings.TrimSuffix(string(html), "</p>"))
+					cp.summary = helpers.BytesToHTML(html)
 				}
 			}
 
@@ -271,7 +282,7 @@ func (p *pageContentOutput) WordCount() int {
 }
 
 func (p *pageContentOutput) setAutoSummary() error {
-	if p.p.source.hasSummaryDivider {
+	if p.p.source.hasSummaryDivider || p.p.m.summary != "" {
 		return nil
 	}
 

hugolib/page_test.go

@@ -45,13 +45,33 @@ const (
 
 	simplePageRFC3339Date = "---\ntitle: RFC3339 Date\ndate: \"2013-05-17T16:59:30Z\"\n---\nrfc3339 content"
 
+	simplePageWithoutSummaryDelimiter = `---
+title: SimpleWithoutSummaryDelimiter
+---
+[Lorem ipsum](https://lipsum.com/) dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+
+Additional text.
+
+Further text.
+`
+
 	simplePageWithSummaryDelimiter = `---
 title: Simple
 ---
 Summary Next Line
 
 <!--more-->
 Some more text
+`
+
+	simplePageWithSummaryParameter = `---
+title: SimpleWithSummaryParameter
+summary: "Page with summary parameter and [a link](http://www.example.com/)"
+---
+
+Some text.
+
+Some more text.
 `
 
 	simplePageWithSummaryDelimiterAndMarkdownThatCrossesBorder = `---
@@ -491,6 +511,22 @@ func TestCreateNewPage(t *testing.T) {
 	testAllMarkdownEnginesForPages(t, assertFunc, settings, simplePage)
 }
 
+func TestPageSummary(t *testing.T) {
+	t.Parallel()
+	assertFunc := func(t *testing.T, ext string, pages page.Pages) {
+		p := pages[0]
+		checkPageTitle(t, p, "SimpleWithoutSummaryDelimiter")
+		// Source is not RST-compatibile so don't test for it
+		if ext != "rst" {
+			checkPageContent(t, p, normalizeExpected(ext, "<p><a href=\"https://lipsum.com/\">Lorem ipsum</a> dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>\n\n<p>Additional text.</p>\n\n<p>Further text.</p>\n"), ext)
+			checkPageSummary(t, p, normalizeExpected(ext, "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Additional text."), ext)
+		}
+		checkPageType(t, p, "page")
+	}
+
+	testAllMarkdownEnginesForPages(t, assertFunc, nil, simplePageWithoutSummaryDelimiter)
+}
+
 func TestPageWithDelimiter(t *testing.T) {
 	t.Parallel()
 	assertFunc := func(t *testing.T, ext string, pages page.Pages) {
@@ -504,6 +540,22 @@ func TestPageWithDelimiter(t *testing.T) {
 	testAllMarkdownEnginesForPages(t, assertFunc, nil, simplePageWithSummaryDelimiter)
 }
 
+func TestPageWithSummaryParameter(t *testing.T) {
+	t.Parallel()
+	assertFunc := func(t *testing.T, ext string, pages page.Pages) {
+		p := pages[0]
+		checkPageTitle(t, p, "SimpleWithSummaryParameter")
+		checkPageContent(t, p, normalizeExpected(ext, "<p>Some text.</p>\n\n<p>Some more text.</p>\n"), ext)
+		// Summary is not RST-compatibile so don't test for it
+		if ext != "rst" {
+			checkPageSummary(t, p, normalizeExpected(ext, "Page with summary parameter and <a href=\"http://www.example.com/\">a link</a>"), ext)
+		}
+		checkPageType(t, p, "page")
+	}
+
+	testAllMarkdownEnginesForPages(t, assertFunc, nil, simplePageWithSummaryParameter)
+}
+
 // Issue #3854
 // Also see https://github.com/gohugoio/hugo/issues/3977
 func TestPageWithDateFields(t *testing.T) {

hugolib/rss_test.go

@@ -55,6 +55,9 @@ func TestRSSOutput(t *testing.T) {
 	if c != rssLimit {
 		t.Errorf("incorrect RSS item count: expected %d, got %d", rssLimit, c)
 	}
+
+	// Encoded summary
+	th.assertFileContent(filepath.Join("public", rssURI), "<?xml", "description", "A &lt;em&gt;custom&lt;/em&gt; summary")
 }
 
 // Before Hugo 0.49 we set the pseudo page kind RSS on the page when output to RSS.

hugolib/site_test.go

@@ -586,6 +586,7 @@ date = "2012-01-01"
 publishdate = "2012-01-01"
 my_param = "baz"
 my_date = 2010-05-27T07:32:00Z
+summary = "A _custom_ summary"
 categories = [ "hugo" ]
 +++
 Front Matter with Ordered Pages 4. This is longer content`