diff options
Diffstat (limited to 'docs/content/en/content-management/summaries.md')
| -rw-r--r-- | docs/content/en/content-management/summaries.md | 137 |
1 files changed, 72 insertions, 65 deletions
diff --git a/docs/content/en/content-management/summaries.md b/docs/content/en/content-management/summaries.md index 22ed3fc81..7b81cf0a0 100644 --- a/docs/content/en/content-management/summaries.md +++ b/docs/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: @@ -13,98 +13,105 @@ toc: true aliases: [/content/summaries/,/content-management/content-summaries/] --- +<!-- Do not remove the manual summary divider below. --> +<!-- If you do, you will break its first literal usage on this page. --> <!--more--> -With the use of the `.Summary` [page variable][pagevariables], 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` [page variables][pagevariables]. +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 and stores it into the `.Summary` page variable for use in your templates. You may customize the summary length by setting `summaryLength` in your [site configuration](/getting-started/configuration/). +Thénardier was not mistaken. The man was sitting there, and letting +Cosette get somewhat rested. -{{% note %}} -You can customize how HTML tags in the summary are loaded using functions such as `plainify` and `safeHTML`. -{{% /note %}} +<!--more--> -{{% 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](/getting-started/configuration/). -{{% /note %}} +The inn-keeper walked round the brushwood and presented himself +abruptly to the eyes of those whom he was in search of. +{{< /code >}} -### Manual summary splitting +When using the Emacs Org Mode [content format], use a `# more` divider to indicate the end of the content summary. -Alternatively, you may add the `<!--more-->` summary divider where you want to split the article. +[content format]: /content-management/formats/ -For [Org mode content][org], use `# more` where you want to split the article. +## Front matter summary -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. +Use front matter to define a summary independent of content. -{{% 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 %}} +{{< 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.' ++++ -Pros -: Freedom, precision, and improved rendering. All HTML tags and formatting are preserved. +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 >}} -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/). +## Automatic summary -{{% note %}} -Be careful to enter `<!--more-->` exactly; i.e., all lowercase and with no whitespace. -{{% /note %}} +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. -### Front matter summary +[`summaryLength`]: /getting-started/configuration/#summarylength -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` variable of the article front matter. +{{< 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 >}} -Pros -: Complete freedom of text independent of the content of the article. Markup can be used within the summary. +For example, with a `summaryLength` of 10, the automatic summary will be: -Cons -: Extra work for content authors as they need to write an entirely separate piece of text as the summary of the article. +```text +Thénardier was not mistaken. The man was sitting there, and letting +Cosette get somewhat rested. +``` -## Summary selection order +Note that the `summaryLength` is an approximate number of words. -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: +## Comparison -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` variable 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 +Each summary type has different characteristics: -{{% note %}} -Hugo uses the _first_ of the above steps that returns text. So if, for example, your article has both `summary` variable in its front matter and a `<!--more-->` summary divider Hugo will use the manual summary split method. -{{% /note %}} +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 matter|2|:heavy_check_mark:|:x:|:x:|:x: +Automatic|3|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:x: -## Example: first 10 articles with summaries +## Rendering -You can show content summaries with the following code. You could use the following snippet, for example, in a [section template]. +Render the summary in a template by calling the [`Summary`] method on a `Page` object. -{{< 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> +[`Summary`]: /methods/page/summary + +```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` boolean variable value may be used to hide the "Read More..." link when the content is not truncated; i.e., when the summary contains the entire article. - -[org]: /content-management/formats/ -[pagevariables]: /variables/page/ -[section template]: /templates/section-templates/ +``` |