mirror/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2025-08-15 20:44:01 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge commit 'de0df119b504a91c9e1f442b07954f366ffb2932'

Browse Source
This commit is contained in:
Bjørn Erik Pedersen
2024-11-13 11:07:57 +01:00
parent e79ee0d516 de0df119b5
commit 3477d9fcec
89 changed files with 745 additions and 856 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/content/en/methods/page/ContentWithoutSummary.md
View File

@@ -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.

25
docs/content/en/methods/page/Language.md
View File

@@ -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

2
docs/content/en/methods/page/Paginate.md
View File

@@ -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.

2
docs/content/en/methods/page/Paginator.md
View File

@@ -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`.

17
docs/content/en/methods/page/RenderShortcodes.md
View File

@@ -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.

14
docs/content/en/methods/page/Scratch.md
View File

@@ -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 }}

8
docs/content/en/methods/page/Store.md
View File

@@ -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 }}

34
docs/content/en/methods/page/Summary.md
View File

@@ -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 %}}

16
docs/content/en/methods/page/Truncated.md
View File

@@ -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 %}}

1
docs/content/en/methods/page/_common/output-format-definition.md
View File

@@ -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&nbsp;[details].
[section]: /getting-started/glossary/#section

2
docs/content/en/methods/resource/Colors.md
View File

@@ -11,8 +11,6 @@ toc: true
math: true
---
{{< new-in 0.104.0 >}}
The `Resources.Colors` method returns a slice of the most dominant colors in an image, ordered from most dominant to least dominant. This method is fast, but if you also downsize your image you can improve performance by extracting the colors from the scaled image.
{{% include "methods/resource/_common/global-page-remote-resources.md" %}}

14
docs/content/en/methods/shortcode/Inner.md
View File

@@ -29,7 +29,7 @@ With this shortcode:
<div class="card-title">{{ . }}</div>
{{ end }}
<div class="card-content">
{{ trim .Inner "\r\n" }}
{{ .Inner | strings.TrimSpace }}
</div>
</div>
{{< /code >}}
@@ -46,9 +46,9 @@ Is rendered to:
```
{{% note %}}
Content between opening and closing shortcode tags may include leading and/or trailing newlines, depending on placement within the Markdown. Use the [`trim`] function as shown above to remove both carriage returns and newlines.
Content between opening and closing shortcode tags may include leading and/or trailing newlines, depending on placement within the Markdown. Use the [`strings.TrimSpace`] function as shown above to remove both carriage returns and newlines.
[`trim`]: /functions/strings/trim/
[`strings.TrimSpace`]: /functions/strings/trimspace/
{{% /note %}}
{{% note %}}
@@ -68,7 +68,7 @@ Let's modify the example above to pass the value returned by `Inner` through the
<div class="card-title">{{ . }}</div>
{{ end }}
<div class="card-content">
{{ trim .Inner "\r\n" | .Page.RenderString }}
{{ .Inner | strings.TrimSpace | .Page.RenderString }}
</div>
</div>
{{< /code >}}
@@ -119,7 +119,7 @@ Second, because we are rendering the entire shortcode as Markdown, we must adher
{{ end }}
<div class="card-content">
{{ trim .Inner "\r\n" }}
{{ .Inner | strings.TrimSpace }}
</div>
</div>
{{< /code >}}
@@ -136,9 +136,9 @@ The difference between this and the previous example is subtle but required. Not
+ <div class="card-title">{{ . }}</div>
{{ end }}
<div class="card-content">
- {{ trim .Inner "\r\n" | .Page.RenderString }}
- {{ .Inner | strings.TrimSpace | .Page.RenderString }}
+
+ {{ trim .Inner "\r\n" }}
+ {{ .Inner | strings.TrimSpace }}
</div>
</div>
```

4
docs/content/en/methods/shortcode/InnerDeindent.md
View File

@@ -38,7 +38,7 @@ With this shortcode, calling `Inner` instead of `InnerDeindent`:
{{< code file=layouts/shortcodes/gallery.html >}}
<div class="gallery">
{{ trim .Inner "\r\n" | .Page.RenderString }}
{{ .Inner | strings.TrimSpace | .Page.RenderString }}
</div>
{{< /code >}}
@@ -69,7 +69,7 @@ Although technically correct per the CommonMark specification, this is not what
{{< code file=layouts/shortcodes/gallery.html >}}
<div class="gallery">
{{ trim .InnerDeindent "\r\n" | .Page.RenderString }}
{{ .InnerDeindent | strings.TrimSpace | .Page.RenderString }}
</div>
{{< /code >}}

2
docs/content/en/methods/shortcode/Parent.md
View File

@@ -21,7 +21,7 @@ Welcome. Today is {{</* now */>}}.
{{< code file=layouts/shortcodes/greeting.html >}}
<div class="greeting">
{{ trim .Inner "\r\n" | .Page.RenderString }}
{{ .Inner | strings.TrimSpace | .Page.RenderString }}
</div>
{{< /code >}}

25
docs/content/en/methods/site/Language.md
View File

@@ -27,36 +27,41 @@ languageName = 'Deutsch'
weight = 1
{{< /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
{{ .Site.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
{{ .Site.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
{{ .Site.Language.LanguageDirection }} → ltr
```
LanguageName
: (`string`) The language name from the site configuration.
###### LanguageName
(`string`) The language name from the site configuration.
```go-html-template
{{ .Site.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
{{ .Site.Language.Weight }} → 1

7
docs/content/en/methods/site/Taxonomies.md
View File

@@ -9,12 +9,9 @@ action:
signatures: [SITE.Taxonomies]
---
<!-- TODO
{{% comment %}}
Show template example: GetTerms
-->
{{% /comment %}}
Conceptually, the `Taxonomies` method on a `Site` object returns a data structure such&nbsp;as: