From d053fa1639e95ff5dea28e8caec8f9190b7b3f9f Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Thu, 5 Sep 2024 09:49:08 -0700 Subject: [PATCH] Update to reflect changes in v0.134.1 --- content/en/content-management/summaries.md | 48 ++++++++++----------- content/en/getting-started/configuration.md | 3 +- content/en/methods/page/Summary.md | 28 +++++++++--- content/en/methods/page/Truncated.md | 16 +++---- 4 files changed, 52 insertions(+), 43 deletions(-) diff --git a/content/en/content-management/summaries.md b/content/en/content-management/summaries.md index e0b2c95908..174495a0c1 100644 --- a/content/en/content-management/summaries.md +++ b/content/en/content-management/summaries.md @@ -17,30 +17,28 @@ aliases: [/content/summaries/,/content-management/content-summaries/] -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. +You can define a summary manually, in front matter, or automatically. A manual summary takes precedence over a front matter summary, and a front matter summary takes precedence over an automatic summary. Review the [comparison table](#comparison) below to understand the characteristics of each summary type. ## Manual summary -Use a `` divider to indicate the end of the content summary. Hugo will not render the summary divider itself. +Use a `` divider to indicate the end of the summary. Hugo will not render the summary divider itself. -{{< code file=content/sample.md >}} +{{< code file=content/example.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. +This is the first paragraph. -The inn-keeper walked round the brushwood and presented himself -abruptly to the eyes of those whom he was in search of. +This is the second paragraph. {{< /code >}} -When using the Emacs Org Mode [content format], use a `# more` divider to indicate the end of the content summary. +When using the Emacs Org Mode [content format], use a `# more` divider to indicate the end of the summary. [content format]: /content-management/formats/ @@ -48,46 +46,44 @@ When using the Emacs Org Mode [content format], use a `# more` divider to indica Use front matter to define a summary independent of content. -{{< code file=content/sample.md >}} +{{< code file=content/example.md >}} +++ title: 'Example' date: 2024-05-26T09:10:33-07:00 -summary: 'Learn more about _Les Misérables_ by Victor Hugo.' +summary: 'This summary is independent of the content.' +++ -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. +This is the first paragraph. + +This is the second paragraph. {{< /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. +If you do not define 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 >}} +{{< code file=content/example.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. +This is the first paragraph. + +This is the second paragraph. + +This is the third paragraph. {{< /code >}} -For example, with a `summaryLength` of 10, the automatic summary will be: +For example, with a `summaryLength` of 7, the automatic summary will be: -```text -Thénardier was not mistaken. The man was sitting there, and letting -Cosette get somewhat rested. +```html +

This is the first paragraph.

+

This is the second paragraph.

``` -Note that the `summaryLength` is an approximate number of words. - ## Comparison Each summary type has different characteristics: diff --git a/content/en/getting-started/configuration.md b/content/en/getting-started/configuration.md index b0a6cae66f..562049434e 100644 --- a/content/en/getting-started/configuration.md +++ b/content/en/getting-started/configuration.md @@ -446,8 +446,9 @@ Default [sitemap configuration](/templates/sitemap/#configuration). ###### summaryLength -(`int`) Applicable to automatic summaries, the approximate number of words to render when calling the [`Summary`] method on a `Page` object. Default is `70`. +(`int`) Applicable to [automatic summaries], the minimum number of words to render when calling the [`Summary`] method on a `Page` object. In this case the `Summary` method returns the content, truncated to the paragraph closest to the `summaryLength`. +[automatic summaries]: /content-management/summaries/#automatic-summary [`Summary`]: /methods/page/summary/ ###### taxonomies diff --git a/content/en/methods/page/Summary.md b/content/en/methods/page/Summary.md index e4542d2581..1612621437 100644 --- a/content/en/methods/page/Summary.md +++ b/content/en/methods/page/Summary.md @@ -1,11 +1,13 @@ --- title: Summary -description: Returns the content summary of the given page. +description: Returns the summary of the given page. categories: [] keywords: [] action: related: - methods/page/Truncated + - methods/page/Content + - methods/page/ContentWithoutSummary - methods/page/Description returnType: template.HTML signatures: [PAGE.Summary] @@ -15,11 +17,9 @@ action: -There are three ways to define the [content summary]: +You can define a [summary] manually, in front matter, or automatically. A manual summary takes precedence over a front matter summary, and a front matter summary takes precedence over an automatic summary. -1. Let Hugo create the summary based on the first 70 words. You can change the number of words by setting the `summaryLength` in your site configuration. -2. Manually split the content with a `` tag in Markdown. Everything before the tag is included in the summary. -3. Create a `summary` field in front matter. +[summary]: /content-management/summaries/ To list the pages in a section with a summary beneath each link: @@ -30,4 +30,20 @@ To list the pages in a section with a summary beneath each link: {{ end }} ``` -[content summary]: /content-management/summaries/ +Depending on content length and how you define the summary, the summary may be equivalent to the content itself. To determine whether the content length exceeds the summary length, use the [`Truncated`] method on a `Page` object. This is useful for conditionally rendering a “read more” link: + +[`Truncated`]: /methods/page/truncated + +```go-html-template +{{ range .Pages }} +

{{ .LinkTitle }}

+ {{ .Summary }} + {{ if .Truncated }} + Read more... + {{ end }} +{{ end }} +``` + +{{% note %}} +The `Truncated` method returns `false` if you define the summary in front matter. +{{% /note %}} diff --git a/content/en/methods/page/Truncated.md b/content/en/methods/page/Truncated.md index 0785f40cb0..b4ec7ce165 100644 --- a/content/en/methods/page/Truncated.md +++ b/content/en/methods/page/Truncated.md @@ -10,17 +10,11 @@ action: signatures: [PAGE.Truncated] --- -There are three ways to define the [content summary]: +You can define a [summary] manually, in front matter, or automatically. A manual summary takes precedence over a front matter summary, and a front matter summary takes precedence over an automatic summary. -1. Let Hugo create the summary based on the first 70 words. You can change the number of words by setting the `summaryLength` in your site configuration. -2. Manually split the content with a `<--more-->` tag in Markdown. Everything before the tag is included in the summary. -3. Create a `summary` field in front matter. +[summary]: /content-management/summaries/ -{{% note %}} -The `Truncated` method returns `false` if you define the summary in front matter. -{{% /note %}} - -The `Truncated` method returns `true` if the content length exceeds the summary length. This is useful for rendering a "read more" link: +The `Truncated` method returns `true` if the content length exceeds the summary length. This is useful for conditionally rendering a "read more" link: ```go-html-template {{ range .Pages }} @@ -32,4 +26,6 @@ The `Truncated` method returns `true` if the content length exceeds the summary {{ end }} ``` -[content summary]: /content-management/summaries/ +{{% note %}} +The `Truncated` method returns `false` if you define the summary in front matter. +{{% /note %}}