Improve content summary page

Closes #2388
Improves #2196

.cspell.json

@@ -115,6 +115,7 @@
     "# cspell: ignore names",
     "# ----------------------------------------------------------------------",
     "Atishay",
+    "Cosette",
     "Eliott",
     "Furet",
     "Gregor",
@@ -125,6 +126,7 @@
     "Pastorius",
     "Samsa",
     "Stucki",
+    "Thénardier",
     "# ----------------------------------------------------------------------",
     "# cspell: ignore operating systems and software packages",
     "# ----------------------------------------------------------------------",

content/en/content-management/summaries.md

@@ -1,7 +1,7 @@
 ---
 title: Content summaries
 linkTitle: Summaries
-description: Hugo generates summaries of your content.
+description: Create and render content summaries.
 categories: [content management]
 keywords: [summaries,abstracts,read more]
 menu:
@@ -17,106 +17,101 @@ aliases: [/content/summaries/,/content-management/content-summaries/]
 <!-- If you do, you will break its first literal usage on this page. -->
 <!--more-->
 
-With the use of the [`Summary`] method on `Page` object, Hugo generates summaries of content to use as a short version in summary views.
+You can define a content summary manually, in front matter, or automatically. A manual content summary takes precedence over a front matter summary, and a front matter summary takes precedence over an automatic summary.
 
-## Summary splitting options
+Review the [comparison table](#comparison) below to understand the characteristics of each summary type.
 
-* Automatic Summary Split
-* Manual Summary Split
-* Front Matter Summary
+## Manual summary
 
-It is natural to accompany the summary with links to the original content, and a common design pattern is to see this link in the form of a "Read More ..." button. See the [`RelPermalink`], [`Permalink`], and [`Truncated`] methods.
+Use a `<!--more-->` divider to indicate the end of the content summary. Hugo will not render the summary divider itself.
 
-### Automatic summary splitting
+{{< code file=content/sample.md >}}
++++
+title: 'Example'
+date: 2024-05-26T09:10:33-07:00
++++
 
-By default, Hugo automatically takes the first 70 words of your content as its summary. Access this value from a template using the [`Summary`] method on a `Page` object. You may customize the summary length by setting [`summaryLength`] in your site configuration.
+Thénardier was not mistaken. The man was sitting there, and letting
+Cosette get somewhat rested.
 
-[`Summary`]: /methods/page/summary
-[`summaryLength`]: /getting-started/configuration/#summarylength
+<--more-->
 
-{{% note %}}
-You can customize how HTML tags in the summary are loaded using functions such as `plainify` and `safeHTML`.
-{{% /note %}}
+The inn-keeper walked round the brushwood and presented himself
+abruptly to the eyes of those whom he was in search of.
+{{< /code >}}
 
-{{% note %}}
-The Hugo-defined summaries are set to use word count calculated by splitting the text by one or more consecutive whitespace characters. If you are creating content in a [`CJK`] language and want to use Hugo's automatic summary splitting, set [`hasCJKLanguage`] to `true` in your site configuration.
+When using the Emacs Org Mode [content format], use a `# more` divider to indicate the end of the content summary.
 
-[`CJK`]: /getting-started/glossary/#cjk
-[`hasCJKLanguage`]: /getting-started/configuration/#hascjklanguage
-{{% /note %}}
+[content format]: /content-management/formats/
 
-### Manual summary splitting
+## Front matter summary
 
-Alternatively, you may add the `<!--more-->` summary divider where you want to split the article.
+Use front matter to define a summary independent of content.
 
-For [Org mode content][org], use `# more` where you want to split the article.
+{{< code file=content/sample.md >}}
++++
+title: 'Example'
+date: 2024-05-26T09:10:33-07:00
+summary: 'Learn more about _Les Misérables_ by Victor Hugo.'
++++
 
-Content that comes before the summary divider will be used as that content's summary and stored in the `.Summary` page variable with all HTML formatting intact.
+Thénardier was not mistaken. The man was sitting there, and letting
+Cosette get somewhat rested. The inn-keeper walked round the
+brushwood and presented himself abruptly to the eyes of those whom
+he was in search of.
+{{< /code >}}
 
-{{% note %}}
-The concept of a *summary divider* is not unique to Hugo. It is also called the "more tag" or "excerpt separator" in other literature.
-{{% /note %}}
+## Automatic summary
 
-Pros
-: Freedom, precision, and improved rendering. All HTML tags and formatting are preserved.
+If you have not defined the summary manually or in front matter, Hugo automatically defines the summary based on the [`summaryLength`] in your site configuration.
 
-Cons
-: Extra work for content authors, since they need to remember to type `<!--more-->` (or `# more` for [org content][org]) in each content file. This can be automated by adding the summary divider below the front matter of an [archetype](/content-management/archetypes/).
+[`summaryLength`]: /getting-started/configuration/#summarylength
 
-{{% note %}}
-Be careful to enter `<!--more-->` exactly; i.e., all lowercase and with no whitespace.
-{{% /note %}}
+{{< code file=content/sample.md >}}
++++
+title: 'Example'
+date: 2024-05-26T09:10:33-07:00
++++
 
-### Front matter summary
+Thénardier was not mistaken. The man was sitting there, and letting
+Cosette get somewhat rested. The inn-keeper walked round the
+brushwood and presented himself abruptly to the eyes of those whom
+he was in search of.
+{{< /code >}}
 
-You might want your summary to be something other than the text that starts the article. In this case you can provide a separate summary in the `summary` field in front matter.
+For example, with a `summaryLength` of 10, the automatic summary will be:
 
-Pros
-: Complete freedom of text independent of the content of the article. Markup can be used within the summary.
+```text
+Thénardier was not mistaken. The man was sitting there, and letting
+Cosette get somewhat rested.
+```
 
-Cons
-: Extra work for content authors as they need to write an entirely separate piece of text as the summary of the article.
+Note that the `summaryLength` is an approximate number of words.
 
-## Summary selection order
+## Comparison
 
-Because there are multiple ways in which a summary can be specified it is useful to understand the order of selection Hugo follows when deciding on the text to be returned by `.Summary`. It is as follows:
+Each summary type has different characteristics:
 
-1. If there is a `<!--more-->` summary divider present in the article, the text up to the divider will be provided as per the manual summary split method
-2. If there is a `summary` field in the article front matter the value of the variable will be provided as per the front matter summary method
-3. The text at the start of the article will be provided as per the automatic summary split method
+Type|Precedence|Renders markdown|Renders shortcodes|Strips HTML tags|Wraps single lines with `<p>`
+:--|:-:|:-:|:-:|:-:|:-:
+Manual|1|:heavy_check_mark:|:heavy_check_mark:|:x:|:heavy_check_mark:
+Front&nbsp;matter|2|:heavy_check_mark:|:x:|:x:|:x:
+Automatic|3|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:x:
 
-{{% note %}}
-Hugo uses the _first_ of the above steps that returns text. So if, for example, your article has both `summary` field in its front matter and a `<!--more-->` summary divider Hugo will use the manual summary split method.
-{{% /note %}}
+## Rendering
 
-## Example: first 10 articles with summaries
+Render the summary in a template by calling the [`Summary`] method on a `Page` object.
 
-You can show content summaries with the following code. You could use the following snippet, for example, in a [section template].
+[`Summary]: /methods/page/summary
 
-{{< code file=page-list-with-summaries.html >}}
-{{ range first 10 .Pages }}
-  <article>
-    <!-- this <div> includes the title summary -->
-    <div>
-      <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
-      {{ .Summary }}
-    </div>
+```go-html-template
+{{ range site.RegularPages }}
+  <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+  <div class="summary">
+    {{ .Summary }}
     {{ if .Truncated }}
-      <!-- This <div> includes a read more link, but only if the summary is truncated... -->
-      <div>
-        <a href="{{ .RelPermalink }}">Read More…</a>
-      </div>
+      <a href="{{ .RelPermalink }}">More ...</a>
     {{ end }}
-  </article>
+  </div>
 {{ end }}
-{{< /code >}}
-
-Note how the `Truncated` method may be used to hide the "Read More..." link when the content is not truncated; i.e., when the summary contains the entire article.
-
-[`Truncated`]: /methods/page/truncated
-[`Permalink`]: /methods/page/permalink/
-[`RelPermalink`]: /methods/page/relpermalink/
-[`Summary`]: /methods/page/summary/
-[`Truncated`]: /methods/page/truncated/
-[org]: /content-management/formats/
-[section template]: /templates/section-templates/
+```

content/en/getting-started/configuration.md

@@ -446,7 +446,9 @@ Default [sitemap configuration](/templates/sitemap-template/#configuration).
 
 ###### summaryLength
 
-(`int`) The length of text in words to show in a [`.Summary`](/content-management/summaries/#automatic-summary-splitting). Default is `70`.
+(`int`) Applicable to automatic summaries, the approximate number of words to render when calling the [`Summary`] method on a `Page` object. Default is `70`.
+
+[`Summary`]: /methods/page/summary/
 
 ###### taxonomies