diff --git a/.cspell.json b/.cspell.json index 62c2576e3d..95e3ed5cee 100644 --- a/.cspell.json +++ b/.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", "# ----------------------------------------------------------------------", diff --git a/content/en/content-management/summaries.md b/content/en/content-management/summaries.md index 2f9c4287a6..7e3979f03e 100644 --- a/content/en/content-management/summaries.md +++ b/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/] -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 `` 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 `` 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 `` (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 `` 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 `` 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 `

` +:--|:-:|:-:|:-:|:-:|:-: +Manual|1|:heavy_check_mark:|:heavy_check_mark:|:x:|:heavy_check_mark: +Front 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 `` 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 }} -

- -
-

{{ .Title }}

- {{ .Summary }} -
+```go-html-template +{{ range site.RegularPages }} +

{{ .LinkTitle }}

+
+ {{ .Summary }} {{ if .Truncated }} - -
- Read More… -
+ More ... {{ end }} -
+ {{ 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/ +``` diff --git a/content/en/getting-started/configuration.md b/content/en/getting-started/configuration.md index 91c58c1d91..aa5971a3bd 100644 --- a/content/en/getting-started/configuration.md +++ b/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