mirror of
https://github.com/gohugoio/hugo.git
synced 2025-08-17 21:01:26 +02:00
Merge commit '8b9803425e63e1b1801f8d5d676e96368d706722'
This commit is contained in:
Bjørn Erik Pedersen
@@ -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 %}}
|
||||
|
||||
### Manual summary splitting
|
||||
|
||||
Alternatively, you may add the `<!--more-->` 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 `<!--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/).
|
||||
|
||||
{{% note %}}
|
||||
Be careful to enter `<!--more-->` 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` variable of the article 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 `<!--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
|
||||
|
||||
{{% 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 %}}
|
||||
|
||||
## 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 }}
|
||||
<article>
|
||||
<!-- this <div> includes the title summary -->
|
||||
<div>
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
|
||||
{{ .Summary }}
|
||||
</div>
|
||||
{{ if .Truncated }}
|
||||
<!-- This <div> includes a read more link, but only if the summary is truncated... -->
|
||||
<div>
|
||||
<a href="{{ .RelPermalink }}">Read More…</a>
|
||||
</div>
|
||||
{{ end }}
|
||||
</article>
|
||||
{{ 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` 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.
|
||||
When using the Emacs Org Mode [content format], use a `# more` divider to indicate the end of the content summary.
|
||||
|
||||
[org]: /content-management/formats/
|
||||
[pagevariables]: /variables/page/
|
||||
[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 `<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:
|
||||
|
||||
## 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 }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
<div class="summary">
|
||||
{{ .Summary }}
|
||||
{{ if .Truncated }}
|
||||
<a href="{{ .RelPermalink }}">More ...</a>
|
||||
{{ end }}
|
||||
</div>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user