mirror/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2025-08-17 21:01:26 +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

4
docs/content/en/content-management/content-adapters.md
View File

@@ -91,6 +91,10 @@ Returns the `Site` to which the pages will be added.
{{ .Site.Title }}
{{< /code >}}
{{% note %}}
Note that the `Site` returned isn't fully built when invoked from the content adapters; if you try to call methods that depends on pages, e.g. `.Site.Pages`, you will get an error saying "this method cannot be called before the site is fully initialized".
{{% /note %}}
###### Store
Returns a persistent “scratch pad” to store and manipulate data. The main use case for this is to transfer values between executions when [EnableAllLanguages](#enablealllanguages) is set. See [examples](/methods/page/store/).

2
docs/content/en/content-management/formats.md
View File

@@ -59,7 +59,7 @@ Create your content in [HTML] preceded by front matter. The content is typically
### Emacs Org Mode
Create your content in the [Emacs Org Mode] format preceded by front matter. You can use Org Mode keywords for front matter. See [details](/content-management/front-matter/#emacs-org-mode)).
Create your content in the [Emacs Org Mode] format preceded by front matter. You can use Org Mode keywords for front matter. See [details](/content-management/front-matter/#emacs-org-mode).
### AsciiDoc

45
docs/content/en/content-management/front-matter.md
View File

@@ -39,7 +39,7 @@ weight = 10
author = 'John Smith'
{{< /code-toggle >}}
Front matter fields may be [scalar], [arrays], or [maps] containing [boolean], [integer], [float], or [string] values. Note that the TOML format also supports date/time values using unquoted strings.
Front matter fields may be [boolean], [integer], [float], [string], [arrays], or [maps]. Note that the TOML format also supports unquoted date/time values.
[scalar]: /getting-started/glossary/#scalar
[arrays]: /getting-started/glossary/#array
@@ -80,7 +80,8 @@ The field names below are reserved. For example, you cannot create a custom fiel
###### date
(`string`) The date associated with the page, typically the creation date. Note that the TOML format also supports date/time values using unquoted strings. Access this value from a template using the [`Date`] method on a `Page` object.
(`string`) The date associated with the page, typically the creation date. Note that the TOML format also supports unquoted date/time values. See the [dates](#dates) section for examples. Access this value from a template using the [`Date`] method on a `Page` object.
[`date`]: /methods/page/date/
@@ -99,7 +100,7 @@ If `true`, the page will not be rendered unless you pass the `--buildDrafts` fla
###### expiryDate
(`string`) The page expiration date. On or after the expiration date, the page will not be rendered unless you pass the `--buildExpired` flag to the `hugo` command. Note that the TOML format also supports date/time values using unquoted strings. Access this value from a template using the [`ExpiryDate`] method on a `Page` object.
(`string`) The page expiration date. On or after the expiration date, the page will not be rendered unless you pass the `--buildExpired` flag to the `hugo` command. Note that the TOML format also supports unquoted date/time values. See the [dates](#dates) section for examples. Access this value from a template using the [`ExpiryDate`] method on a `Page` object.
[`expirydate`]: /methods/page/expirydate/
@@ -127,6 +128,7 @@ If `true`, the page will not be rendered unless you pass the `--buildDrafts` fla
[`keywords`]: /methods/page/keywords/
[taxonomy]: /getting-started/glossary/#taxonomy
{{% comment %}}
<!-- Added in v0.123.0 but purposefully omitted from documentation. -->
<!--
kind
@@ -138,10 +140,11 @@ kind
lang
: The language code for this page. This is usually derived from the module mount or filename.
-->
{{% /comment %}}
###### lastmod
(`string`) The date that the page was last modified. Note that the TOML format also supports date/time values using unquoted strings. Access this value from a template using the [`Lastmod`] method on a `Page` object.
(`string`) The date that the page was last modified. Note that the TOML format also supports unquoted date/time values. See the [dates](#dates) section for examples. Access this value from a template using the [`Lastmod`] method on a `Page` object.
[`lastmod`]: /methods/page/date/
@@ -167,21 +170,27 @@ lang
###### menus
(`string`,`string array`, or `map`) If set, Hugo adds the page to the given menu or menus. See the [menus] page for details.
(`string`, `string array`, or `map`) If set, Hugo adds the page to the given menu or menus. See the [menus] page for details.
[menus]: /content-management/menus/#define-in-front-matter
###### modified
Alias to [lastmod](#lastmod).
###### outputs
(`string array`) The [output formats] to render.
[output formats]: /templates/output-formats/
{{% comment %}}
<!-- Added in v0.123.0 but purposefully omitted from documentation. -->
<!--
path
: The canonical page path.
-->
{{% /comment %}}
###### params
@@ -191,12 +200,20 @@ path
[page parameters]: #parameters
###### pubdate
Alias to [publishDate](#publishdate).
###### publishDate
(`string`) The page publication date. Before the publication date, the page will not be rendered unless you pass the `--buildFuture` flag to the `hugo` command. Note that the TOML format also supports date/time values using unquoted strings. Access this value from a template using the [`PublishDate`] method on a `Page` object.
(`string`) The page publication date. Before the publication date, the page will not be rendered unless you pass the `--buildFuture` flag to the `hugo` command. Note that the TOML format also supports unquoted date/time values. See the [dates](#dates) section for examples. Access this value from a template using the [`PublishDate`] method on a `Page` object.
[`publishdate`]: /methods/page/publishdate/
###### published
Alias to [publishDate](#publishdate).
###### resources
(`map array`) An array of maps to provide metadata for [page resources].
@@ -242,6 +259,10 @@ path
[content type]: /getting-started/glossary/#content-type
[`type`]: /methods/page/type/
###### unpublishdate
Alias to [expirydate](#expirydate).
###### url
(`string`) Overrides the entire URL path. Applicable to regular pages and section pages. See the [URL management] page for details.
@@ -428,3 +449,15 @@ Note that you can also specify array elements on a single line:
[content format]: /content-management/formats/
[emacs org mode]: https://orgmode.org/
## Dates
When populating a date field, whether a [custom page parameter](#parameters) or one of the four predefined fields ([`date`](#date), [`expiryDate`](#expirydate), [`lastmod`](#lastmod), [`publishDate`](#publishdate)), use one of these parsable formats:
{{% include "functions/time/_common/parsable-date-time-strings.md" %}}
To override the default time zone, set the [`timeZone`](https://gohugo.io/getting-started/configuration/#timezone) in your site configuration. The order of precedence for determining the time zone is:
1. The time zone offset in the date/time string
2. The time zone specified in your site configuration
3. The `Etc/UTC` time zone

2
docs/content/en/content-management/image-processing/index.md
View File

@@ -205,8 +205,6 @@ Sometimes it can be useful to create the filter chain once and then reuse it.
### Colors
{{< new-in 0.104.0 >}}
`.Colors` returns a slice of hex strings with the dominant colors in the image using a simple histogram method.
```go-html-template

2
docs/content/en/content-management/menus.md
View File

@@ -100,7 +100,7 @@ This front matter menu entry demonstrates some of the available properties:
{{< code-toggle file=content/products/software.md fm=true >}}
title = 'Software'
[[menus.main]]
[menus.main]
parent = 'Products'
weight = 20
pre = '<i class="fa-solid fa-code"></i>'

2
docs/content/en/content-management/multilingual.md
View File

@@ -136,7 +136,7 @@ In the example above, all settings except `color` below `params` map to predefin
```go-html-template
{{ site.Title }}
{{ site.LanguageCode }}
{{ site.Language.LanguageCode }}
{{ site.Params.color }}
```

20
docs/content/en/content-management/shortcodes.md
View File

@@ -74,6 +74,26 @@ You can call shortcodes within other shortcodes by creating your own templates t
Use these embedded shortcodes as needed.
### comment
{{< new-in "0.137.1" >}}
{{% note %}}
To override Hugo's embedded `comment` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
[source code]: {{% eturl comment %}}
{{% /note %}}
Use the `comment` shortcode to include comments in your Markdown. Hugo excludes the encapsulated text when rendering your site.
Example usage:
```text
{{%/* comment */%}} TODO: rewrite the paragraph below. {{%/* /comment */%}}
```
Although you can call this shortcode using the `{{</* */>}}` notation, computationally it is more efficient to call it using the `{{%/* */%}}` notation as shown above.
### figure
{{% note %}}

66
docs/content/en/content-management/summaries.md
View File

@@ -12,35 +12,34 @@ weight: 160
toc: true
aliases: [/content/summaries/,/content-management/content-summaries/]
---
{{% comment %}}
<!-- Do not remove the manual summary divider below. -->
<!-- If you do, you will break its first literal usage on this page. -->
{{% /comment %}}
<!--more-->
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 `<!--more-->` divider to indicate the end of the content summary. Hugo will not render the summary divider itself.
Use a `<!--more-->` 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.
<!--more-->
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 +47,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
<p>This is the first paragraph.</p>
<p>This is the second paragraph.</p>
```
Note that the `summaryLength` is an approximate number of words.
## Comparison
Each summary type has different characteristics:
@@ -115,3 +112,18 @@ Render the summary in a template by calling the [`Summary`] method on a `Page` o
</div>
{{ end }}
```
## Alternative
Instead of calling the `Summary` method on a `Page` object, use the [`strings.Truncate`] function for granular control of the summary length. For example:
[`strings.Truncate`]: /functions/strings/truncate/
```go-html-template
{{ range site.RegularPages }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
<div class="summary">
{{ .Content | strings.Truncate 42 }}
</div>
{{ end }}
```

61
docs/content/en/content-management/urls.md
View File

@@ -43,11 +43,45 @@ https://example.org/posts/my-first-post/
Set the `url` in front matter to override the entire path. Use this with either regular pages or section pages.
{{% note %}}
Hugo does not sanitize the `url` front matter field, allowing you to generate:
- File paths that contain characters reserved by the operating system. For example, file paths on Windows may not contain any of these [reserved characters]. Hugo throws an error if a file path includes a character reserved by the current operating system.
- URLs that contain disallowed characters. For example, the less than sign (`<`) is not allowed in a URL.
[reserved characters]: https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file#naming-conventions
{{% /note %}}
If you set both `slug` and `url` in front matter, the `url` value takes precedence.
#### Include a colon
{{< new-in 0.136.0 >}}
If you need to include a colon in the `url` front matter field, escape it with backslash characters. Use one backslash if you wrap the string within single quotes, or use two backslashes if you wrap the string within double quotes. With YAML front matter, use a single backslash if you omit quotation marks.
For example, with this front matter:
{{< code-toggle file=content/example.md fm=true >}}
title: Example
url: "my\\:example"
{{< /code-toggle >}}
The resulting URL will be:
```text
https://example.org/my:example/
```
As described above, this will fail on Windows because the colon (`:`) is a reserved character.
#### File extensions
With this front matter:
{{< code-toggle file=content/posts/post-1.md fm=true >}}
title = 'My First Article'
url = '/articles/my-first-article'
url = 'articles/my-first-article'
{{< /code-toggle >}}
The resulting URL will be:
@@ -60,7 +94,7 @@ If you include a file extension:
{{< code-toggle file=content/posts/post-1.md fm=true >}}
title = 'My First Article'
url = '/articles/my-first-article.html'
url = 'articles/my-first-article.html'
{{< /code-toggle >}}
The resulting URL will be:
@@ -69,12 +103,11 @@ The resulting URL will be:
https://example.org/articles/my-first-article.html
```
In a monolingual site, a `url` value with or without a leading slash is relative to the `baseURL`.
#### Leading slashes
In a multilingual site:
With monolingual sites, `url` values with or without a leading slash are relative to the [`baseURL`]. With multilingual sites, `url` values with a leading slash are relative to the `baseURL`, and `url` values without a leading slash are relative to the `baseURL` plus the language prefix.
- A `url` value with a leading slash is relative to the `baseURL`.
- A `url` value without a leading slash is relative to the `baseURL` plus the language prefix.
[`baseURL`]: /getting-started/configuration/#baseurl
Site type|Front matter `url`|Resulting URL
:--|:--|:--
@@ -83,13 +116,11 @@ monolingual|`about`|`https://example.org/about/`
multilingual|`/about`|`https://example.org/about/`
multilingual|`about`|`https://example.org/de/about/`
If you set both `slug` and `url` in front matter, the `url` value takes precedence.
#### Permalinks tokens in front matter
{{< new-in "0.131.0" >}}
You can also use [Permalinks tokens](#tokens) in the `url` front matter. This is typically used in `cascade` sections:
You can also use [tokens](#tokens) when setting the `url` value. This is typically used in `cascade` sections:
{{< code-toggle file=content/foo/bar/_index.md fm=true >}}
title ="Bar"
@@ -246,9 +277,7 @@ public/
#### Tokens
Use these tokens when defining the URL pattern. These can both be used in the `permalinks` configuration and in the front matter [url](#permalinks-tokens-in-front-matter).
`:filename`
Use these tokens when defining the URL pattern. You can also use these tokens when setting the [`url`](#permalinks-tokens-in-front-matter) value in front matter.
`:year`
: The 4-digit year as defined in the front matter `date` field.
@@ -313,6 +342,14 @@ By default, Hugo produces pretty URLs. To generate ugly URLs, change your site c
uglyURLs = true
{{< /code-toggle >}}
You can also enable uglyURLs by section. For example, with a site that contains sections for books and films:
{{< code-toggle file=hugo >}}
[uglyURLs]
books = true
films = false
{{< /code-toggle >}}
### Post-processing
Hugo provides two mutually exclusive configuration options to alter URLs _after_ it renders a page.