diff options
Diffstat (limited to 'docs/content/en/methods/page')
| -rw-r--r-- | docs/content/en/methods/page/ContentWithoutSummary.md | 2 | ||||
| -rw-r--r-- | docs/content/en/methods/page/Language.md | 25 | ||||
| -rw-r--r-- | docs/content/en/methods/page/Paginate.md | 2 | ||||
| -rw-r--r-- | docs/content/en/methods/page/Paginator.md | 2 | ||||
| -rw-r--r-- | docs/content/en/methods/page/RenderShortcodes.md | 17 | ||||
| -rw-r--r-- | docs/content/en/methods/page/Scratch.md | 14 | ||||
| -rw-r--r-- | docs/content/en/methods/page/Store.md | 8 | ||||
| -rw-r--r-- | docs/content/en/methods/page/Summary.md | 34 | ||||
| -rw-r--r-- | docs/content/en/methods/page/Truncated.md | 16 | ||||
| -rw-r--r-- | docs/content/en/methods/page/_common/output-format-definition.md | 1 |
10 files changed, 79 insertions, 42 deletions
diff --git a/docs/content/en/methods/page/ContentWithoutSummary.md b/docs/content/en/methods/page/ContentWithoutSummary.md index 5080f6717..44d660cef 100644 --- a/docs/content/en/methods/page/ContentWithoutSummary.md +++ b/docs/content/en/methods/page/ContentWithoutSummary.md @@ -25,4 +25,4 @@ Applicable when using manual or automatic [content summaries], the `ContentWitho {{ .ContentWithoutSummary }} ``` -The `ContentWithoutSummary` method returns an empty string if you define the content summary in front matter. +The `ContentWithoutSummary` method returns the same as `Content` if you define the content summary in front matter. diff --git a/docs/content/en/methods/page/Language.md b/docs/content/en/methods/page/Language.md index 321b44e56..e12fc2e62 100644 --- a/docs/content/en/methods/page/Language.md +++ b/docs/content/en/methods/page/Language.md @@ -26,36 +26,41 @@ languageName = 'Deutsch' weight = 2 {{< /code-toggle >}} -Lang -: (`string`) The language tag as defined by [RFC 5646]. +###### Lang + +(`string`) The language tag as defined by [RFC 5646]. ```go-html-template {{ .Language.Lang }} → de ``` -LanguageCode -: (`string`) The language code from the site configuration. Falls back to `Lang` if not defined. +###### LanguageCode + +(`string`) The language code from the site configuration. Falls back to `Lang` if not defined. ```go-html-template {{ .Language.LanguageCode }} → de-DE ``` -LanguageDirection -: (`string`) The language direction from the site configuration, either `ltr` or `rtl`. +###### LanguageDirection + +(`string`) The language direction from the site configuration, either `ltr` or `rtl`. ```go-html-template {{ .Language.LanguageDirection }} → ltr ``` -LanguageName -: (`string`) The language name from the site configuration. +###### LanguageName + +(`string`) The language name from the site configuration. ```go-html-template {{ .Language.LanguageName }} → Deutsch ``` -Weight -: (`int`) The language weight from the site configuration which determines its order in the slice of languages returned by the `Languages` method on a `Site` object. +###### Weight + +(`int`) The language weight from the site configuration which determines its order in the slice of languages returned by the `Languages` method on a `Site` object. ```go-html-template {{ .Language.Weight }} → 2 diff --git a/docs/content/en/methods/page/Paginate.md b/docs/content/en/methods/page/Paginate.md index d9acb6b93..02daa64b4 100644 --- a/docs/content/en/methods/page/Paginate.md +++ b/docs/content/en/methods/page/Paginate.md @@ -10,7 +10,7 @@ action: signatures: ['PAGE.Paginate COLLECTION [N]'] --- -[Pagination] is the process of splitting a list page into two or more pagers, where each pager contains a subset of the page collection and navigation links to other pagers. +Pagination is the process of splitting a list page into two or more pagers, where each pager contains a subset of the page collection and navigation links to other pagers. By default, the number of elements on each pager is determined by your [site configuration]. The default is `10`. Override that value by providing a second argument, an integer, when calling the `Paginate` method. diff --git a/docs/content/en/methods/page/Paginator.md b/docs/content/en/methods/page/Paginator.md index f57e2437e..3dd959006 100644 --- a/docs/content/en/methods/page/Paginator.md +++ b/docs/content/en/methods/page/Paginator.md @@ -10,7 +10,7 @@ action: signatures: [PAGE.Paginator] --- -[Pagination] is the process of splitting a list page into two or more pagers, where each pager contains a subset of the page collection and navigation links to other pagers. +Pagination is the process of splitting a list page into two or more pagers, where each pager contains a subset of the page collection and navigation links to other pagers. The number of elements on each pager is determined by your [site configuration]. The default is `10`. diff --git a/docs/content/en/methods/page/RenderShortcodes.md b/docs/content/en/methods/page/RenderShortcodes.md index 9679fc8d5..e95e0683e 100644 --- a/docs/content/en/methods/page/RenderShortcodes.md +++ b/docs/content/en/methods/page/RenderShortcodes.md @@ -32,9 +32,9 @@ For example: Then call the shortcode in your Markdown: {{< code file=content/about.md lang=md >}} -{{%/* include "/snippets/services.md" */%}} -{{%/* include "/snippets/values.md" */%}} -{{%/* include "/snippets/leadership.md" */%}} +{{%/* include "/snippets/services" */%}} +{{%/* include "/snippets/values" */%}} +{{%/* include "/snippets/leadership" */%}} {{< /code >}} Each of the included Markdown files can contain calls to other shortcodes. @@ -79,3 +79,14 @@ An *emphasized* word. ``` Note that the shortcode within the content file was rendered, but the surrounding Markdown was preserved. + + +## Limitations + +The primary use case for `.RenderShortcodes` is inclusion of Markdown content. If you try to use `.RenderShortcodes` inside `HTML` blocks when inside Markdown, you will get a warning similar to this: + +``` +WARN .RenderShortcodes detected inside HTML block in "/content/mypost.md"; this may not be what you intended ... +``` + +The above warning can be turned off is this is what you really want. diff --git a/docs/content/en/methods/page/Scratch.md b/docs/content/en/methods/page/Scratch.md index 8fef31893..41b1d17fd 100644 --- a/docs/content/en/methods/page/Scratch.md +++ b/docs/content/en/methods/page/Scratch.md @@ -13,6 +13,16 @@ toc: true aliases: [/extras/scratch/,/doc/scratch/,/functions/scratch] --- +{{% deprecated-in 0.138.0 %}} +Use the [`PAGE.Store`] method instead. + +This is a soft deprecation. This method will be removed in a future release, but the removal date has not been established. Although Hugo will not emit a warning if you continue to use this method, you should begin using `PAGE.Store` as soon as possible. + +Beginning with v0.138.0 the `PAGE.Scratch` method is aliased to `PAGE.Store`. + +[`PAGE.Store`]: /methods/page/store/ +{{% /deprecated-in %}} + The `Scratch` method on a `Page` object creates a [scratch pad] to store and manipulate data. To create a scratch pad that is not reset on server rebuilds, use the [`Store`] method instead. To create a locally scoped scratch pad that is not attached to a `Page` object, use the [`newScratch`] function. @@ -25,7 +35,7 @@ To create a locally scoped scratch pad that is not attached to a `Page` object, ## Determinate values -The `Scratch` method is often used to set scratch pad values within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are not determinate until Hugo renders the page content. +The `Scratch` method is often used to set scratch pad values within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are indeterminate until Hugo renders the page content. If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop] variable: @@ -36,7 +46,7 @@ If you need to access a scratch pad value from a parent template, and the parent {{ .Store.Get "mykey" }} ``` -You can also trigger content rendering with the `FuzzyWordCount`, `Len`, `Plain`, `PlainWords`, `ReadingTime`, `Summary`, `Truncated`, and `WordCount` methods. For example: +You can also trigger content rendering with the `ContentWithoutSummary`, `FuzzyWordCount`, `Len`, `Plain`, `PlainWords`, `ReadingTime`, `Summary`, `Truncated`, and `WordCount` methods. For example: ```go-html-template {{ $noop := .WordCount }} diff --git a/docs/content/en/methods/page/Store.md b/docs/content/en/methods/page/Store.md index e7090fe79..a81fa71a3 100644 --- a/docs/content/en/methods/page/Store.md +++ b/docs/content/en/methods/page/Store.md @@ -13,9 +13,7 @@ toc: true aliases: [/functions/store] --- -The `Store` method on a `Page` object creates a persistent [scratch pad] to store and manipulate data. In contrast with the [`Scratch`] method, the scratch pad created by the `Store` method is not reset on server rebuilds. - -To create a locally scoped scratch pad that is not attached to a `Page` object, use the [`newScratch`] function. +The `Store` method on a `Page` object creates a persistent [scratch pad] to store and manipulate data. To create a locally scoped scratch pad that is not attached to a `Page` object, use the [`newScratch`] function. [`Scratch`]: /methods/page/scratch/ [`newScratch`]: /functions/collections/newscratch/ @@ -106,7 +104,7 @@ Removes the given key. ## Determinate values -The `Store` method is often used to set scratch pad values within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are not determinate until Hugo renders the page content. +The `Store` method is often used to set scratch pad values within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are indeterminate until Hugo renders the page content. If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop] variable: @@ -117,7 +115,7 @@ If you need to access a scratch pad value from a parent template, and the parent {{ .Store.Get "mykey" }} ``` -You can also trigger content rendering with the `FuzzyWordCount`, `Len`, `Plain`, `PlainWords`, `ReadingTime`, `Summary`, `Truncated`, and `WordCount` methods. For example: +You can also trigger content rendering with the `ContentWithoutSummary`, `FuzzyWordCount`, `Len`, `Plain`, `PlainWords`, `ReadingTime`, `Summary`, `Truncated`, and `WordCount` methods. For example: ```go-html-template {{ $noop := .WordCount }} diff --git a/docs/content/en/methods/page/Summary.md b/docs/content/en/methods/page/Summary.md index e4542d258..490b201d0 100644 --- a/docs/content/en/methods/page/Summary.md +++ b/docs/content/en/methods/page/Summary.md @@ -1,25 +1,27 @@ --- 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] --- -<!-- Do not remove the manual summary divider below. --> -<!-- If you do, you will break its first literal usage on this page. --> +{{% comment %}} +Do not remove the manual summary divider below. +If you do, you will break its first literal usage on this page. +{{% /comment %}} <!--more--> -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/ To list the pages in a section with a summary beneath each link: @@ -30,4 +32,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 }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> + {{ .Summary }} + {{ if .Truncated }} + <a href="{{ .RelPermalink }}">Read more...</a> + {{ end }} +{{ end }} +``` + +{{% note %}} +The `Truncated` method returns `false` if you define the summary in front matter. +{{% /note %}} diff --git a/docs/content/en/methods/page/Truncated.md b/docs/content/en/methods/page/Truncated.md index 0785f40cb..b4ec7ce16 100644 --- a/docs/content/en/methods/page/Truncated.md +++ b/docs/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 %}} diff --git a/docs/content/en/methods/page/_common/output-format-definition.md b/docs/content/en/methods/page/_common/output-format-definition.md index 412c5cee6..d21211a3d 100644 --- a/docs/content/en/methods/page/_common/output-format-definition.md +++ b/docs/content/en/methods/page/_common/output-format-definition.md @@ -1,7 +1,6 @@ --- # Do not remove front matter. --- - Hugo generates one or more files per page when building a site. For example, when rendering home, [section], [taxonomy], and [term] pages, Hugo generates an HTML file and an RSS file. Both HTML and RSS are built-in _output formats_. Create multiple output formats, and control generation based on [page kind], or by enabling one or more output formats for one or more pages. See [details]. [section]: /getting-started/glossary/#section |