diff --git a/.cspell.json b/.cspell.json index 62c2576e3..95e3ed5ce 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 2f9c4287a..7e3979f03 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 %}} - -{{% 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. - -[`CJK`]: /getting-started/glossary/#cjk -[`hasCJKLanguage`]: /getting-started/configuration/#hascjklanguage -{{% /note %}} - -### Manual summary splitting - -Alternatively, you may add the `` summary divider where you want to split the article. - -For [Org mode content][org], use `# more` where you want to split the article. - -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. - -{{% 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 %}} - -Pros -: Freedom, precision, and improved rendering. All HTML tags and formatting are preserved. - -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/). - -{{% note %}} -Be careful to enter `` exactly; i.e., all lowercase and with no whitespace. -{{% /note %}} - -### Front matter summary - -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. - -Pros -: Complete freedom of text independent of the content of the article. Markup can be used within the summary. - -Cons -: Extra work for content authors as they need to write an entirely separate piece of text as the summary of the article. - -## Summary selection order - -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: - -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 - -{{% 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 %}} - -## Example: first 10 articles with summaries - -You can show content summaries with the following code. You could use the following snippet, for example, in a [section template]. - -{{< code file=page-list-with-summaries.html >}} -{{ range first 10 .Pages }} -
- -
-

{{ .Title }}

- {{ .Summary }} -
- {{ if .Truncated }} - -
- Read More… -
- {{ end }} -
-{{ end }} +The inn-keeper walked round the brushwood and presented himself +abruptly to the eyes of those whom he was in search of. {{< /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. +When using the Emacs Org Mode [content format], use a `# more` divider to indicate the end of the content summary. -[`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 format]: /content-management/formats/ + +## Front matter summary + +Use front matter to define a summary independent of content. + +{{< 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.' ++++ + +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 >}} + +## Automatic summary + +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. + +[`summaryLength`]: /getting-started/configuration/#summarylength + +{{< code file=content/sample.md >}} ++++ +title: 'Example' +date: 2024-05-26T09:10:33-07:00 ++++ + +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 >}} + +For example, with a `summaryLength` of 10, the automatic summary will be: + +```text +Thénardier was not mistaken. The man was sitting there, and letting +Cosette get somewhat rested. +``` + +Note that the `summaryLength` is an approximate number of words. + +## Comparison + +Each summary type has different characteristics: + +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: + +## Rendering + +Render the summary in a template by calling the [`Summary`] method on a `Page` object. + +[`Summary]: /methods/page/summary + +```go-html-template +{{ range site.RegularPages }} +

{{ .LinkTitle }}

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