-
-
- 
+ 
+
+
Author: {{ .Params.author }}
+ +
+ ISBN: {{ .Params.isbn }}
+ Rating: {{ .Params.rating }}
+ Review date: {{ .Date | time.Format ":date_long" }}
+
Tags:
+| {{ . }} | + {{ end }} +
|---|
| {{ . }} | + {{ end }} +
{{- .Inner | safeHTML }}
{{ .Page.Store.Set "hasMermaid" true }}
-```
+{{< /code >}}
-And then include this snippet at the bottom of the content template (**Note**: below `.Content` as the render hook is not processed until `.Content` is executed):
+And then include this snippet at the bottom of the content template:
```go-html-template
-{{ if .Page.Store.Get "hasMermaid" }}
+{{ if .Store.Get "hasMermaid" }}
` → ``
-* `` → ``
+Use the `safe.JS` function to encapsulate a known safe EcmaScript5 Expression.
+
+Template authors are responsible for ensuring that typed expressions do not break the intended precedence and that there is no statement/expression ambiguity as when passing an expression like `{ foo: bar() }\n['foo']()`, which is both a valid Expression and a valid Program with a very different meaning.
+
+Use of this type presents a security risk: the encapsulated content should come from a trusted source, as it will be included verbatim in the template output.
+
+Using the `safe.JS` function to include valid but untrusted JSON is not safe. A safe alternative is to parse the JSON with the [`transform.Unmarshal`] function and then pass the resultant object into the template, where it will be converted to sanitized JSON when presented in a JavaScript context.
+
+[`transform.Unmarshal`]: /functions/transform/unmarshal/
+
+See the [Go documentation] for details.
+
+[Go documentation]: https://pkg.go.dev/html/template#JS
+
+## Example
+
+Without a safe declaration:
+
+```go-html-template
+{{ $js := "x + y" }}
+
+```
+
+Hugo renders the above to:
+
+```html
+
+```
+
+To declare the string as safe:
+
+```go-html-template
+{{ $js := "x + y" }}
+
+```
+
+Hugo renders the above to:
+
+```html
+
+```
diff --git a/docs/content/en/functions/safe/JSStr.md b/docs/content/en/functions/safe/JSStr.md
index 36d2b36fa..e7e232d1b 100644
--- a/docs/content/en/functions/safe/JSStr.md
+++ b/docs/content/en/functions/safe/JSStr.md
@@ -13,12 +13,27 @@ action:
- functions/safe/URL
returnType: template.JSStr
signatures: [safe.JSStr INPUT]
+toc: true
aliases: [/functions/safejsstr]
---
-Encapsulates a sequence of characters meant to be embedded between quotes in a JavaScript expression. Use of this type presents a security risk: the encapsulated content should come from a trusted source, as it will be included verbatim in the template output.
-
-Without declaring a variable to be a safe JavaScript string:
+## Introduction
+
+{{% include "functions/_common/go-html-template-package.md" %}}
+
+## Usage
+
+Use the `safe.JSStr` function to encapsulate a sequence of characters meant to be embedded between quotes in a JavaScript expression.
+
+Use of this type presents a security risk: the encapsulated content should come from a trusted source, as it will be included verbatim in the template output.
+
+See the [Go documentation] for details.
+
+[Go documentation]: https://pkg.go.dev/html/template#JSStr
+
+## Example
+
+Without a safe declaration:
```go-html-template
{{ $title := "Lilo & Stitch" }}
@@ -27,7 +42,7 @@ Without declaring a variable to be a safe JavaScript string:
```
-Rendered:
+Hugo renders the above to:
```html
```
-To avoid escaping by Go's [html/template] package:
+To declare the string as safe:
```go-html-template
{{ $title := "Lilo & Stitch" }}
@@ -44,12 +59,10 @@ To avoid escaping by Go's [html/template] package:
```
-Rendered:
+Hugo renders the above to:
```html
```
-
-[html/template]: https://pkg.go.dev/html/template
diff --git a/docs/content/en/functions/safe/URL.md b/docs/content/en/functions/safe/URL.md
index 2da6895e5..e4b3224da 100644
--- a/docs/content/en/functions/safe/URL.md
+++ b/docs/content/en/functions/safe/URL.md
@@ -13,58 +13,56 @@ action:
- functions/safe/JSStr
returnType: template.URL
signatures: [safe.URL INPUT]
+toc: true
aliases: [/functions/safeurl]
---
-`safeURL` declares the provided string as a "safe" URL or URL substring (see [RFC 3986]). A URL like `javascript:checkThatFormNotEditedBeforeLeavingPage()` from a trusted source should go in the page, but by default dynamic `javascript:` URLs are filtered out since they are a frequently exploited injection vector.
+## Introduction
-Without `safeURL`, only the URI schemes `http:`, `https:` and `mailto:` are considered safe by Go templates. If any other URI schemes (e.g., `irc:` and `javascript:`) are detected, the whole URL will be replaced with `#ZgotmplZ`. This is to "defang" any potential attack in the URL by rendering it useless.
+{{% include "functions/_common/go-html-template-package.md" %}}
-The following examples use a [site `hugo.toml`][configuration] with the following [menu entry][menus]:
+## Usage
-{{< code-toggle file=hugo >}}
-[[menus.main]]
-name = "IRC: #golang at freenode"
-url = "irc://irc.freenode.net/#golang"
-{{< /code-toggle >}}
+Use the `safe.URL` function to encapsulate a known safe URL or URL substring. Schemes other than the following are considered unsafe:
-The following is an example of a sidebar partial that may be used in conjunction with the preceding front matter example:
+- `http:`
+- `https:`
+- `mailto:`
-{{< code file=layouts/partials/bad-url-sidebar-menu.html >}}
-
-The product of 6 and 7 is 42.
+The product of 7 and 6 is 42.
+`}} + +{{ $got := ` +The product of 6 and 7 is 42.
+The product of 7 and 6 is 13.
+`}} + +{{ $diff := strings.Diff "want" $want "got" $got }} +{{ transform.Highlight $diff "diff" }} +``` + +Rendered: + + diff --git a/docs/content/en/functions/strings/FindRESubmatch.md b/docs/content/en/functions/strings/FindRESubmatch.md index 302d1d9b4..3feb15bbd 100644 --- a/docs/content/en/functions/strings/FindRESubmatch.md +++ b/docs/content/en/functions/strings/FindRESubmatch.md @@ -30,7 +30,7 @@ By default, `findRESubmatch` finds all matches. You can limit the number of matc ## Practical example -This markdown: +This Markdown: ```text - [Example](https://example.org) diff --git a/docs/content/en/functions/strings/RuneCount.md b/docs/content/en/functions/strings/RuneCount.md index 46fedf01f..86aab0c64 100644 --- a/docs/content/en/functions/strings/RuneCount.md +++ b/docs/content/en/functions/strings/RuneCount.md @@ -21,4 +21,4 @@ In contrast with the [`strings.CountRunes`] function, which excludes whitespace, {{ "Hello, 世界" | strings.RuneCount }} → 9 ``` -[`strings.CountRunes`]: /functions/strings/countrunes +[`strings.CountRunes`]: /functions/strings/countrunes/ diff --git a/docs/content/en/functions/strings/SliceString.md b/docs/content/en/functions/strings/SliceString.md index 2f33f8f65..ee4ed9081 100644 --- a/docs/content/en/functions/strings/SliceString.md +++ b/docs/content/en/functions/strings/SliceString.md @@ -1,20 +1,26 @@ --- title: strings.SliceString -description: Creates a slice of a half-open range, including start and end indices. +description: Returns a substring of the given string, beginning with the start position and ending before the end position. categories: [] keywords: [] action: aliases: [slicestr] - related: [] + related: + - functions/strings/Substr returnType: string - signatures: ['strings.SliceString STRING START [END]'] + signatures: ['strings.SliceString STRING [START] [END]'] aliases: [/functions/slicestr] --- -For example, 1 and 4 creates a slice including elements 1 through 3. -The `end` index can be omitted; it defaults to the string's length. +The START and END positions are zero-based, where `0` represents the first character of the string. If START is not specified, the substring will begin at position `0`. If END is not specified, the substring will end after the last character. ```go-html-template -{{ slicestr "BatMan" 3 }}` → Man -{{ slicestr "BatMan" 0 3 }}` → Bat +{{ slicestr "BatMan" }} → BatMan +{{ slicestr "BatMan" 3 }} → Man +{{ slicestr "BatMan" 0 3 }} → Bat ``` + +The START and END arguments represent the endpoints of a [half-open interval], a concept that may be difficult to grasp when first encountered. You may find that the [`strings.Substr`] function is easier to understand. + +[half-open interval]: /getting-started/glossary/#interval +[`strings.Substr`]: /functions/strings/substr/ diff --git a/docs/content/en/functions/strings/Split.md b/docs/content/en/functions/strings/Split.md index a9973ea63..e3e0ee13e 100644 --- a/docs/content/en/functions/strings/Split.md +++ b/docs/content/en/functions/strings/Split.md @@ -22,5 +22,5 @@ Examples: {{% note %}} The `strings.Split` function essentially does the opposite of the [`collections.Delimit`] function. While `split` creates a slice from a string, `delimit` creates a string from a slice. -[`collections.Delimit`]: /functions/collections/delimit +[`collections.Delimit`]: /functions/collections/delimit/ {{% /note %}} diff --git a/docs/content/en/functions/strings/Substr.md b/docs/content/en/functions/strings/Substr.md index 6c1852f58..19a029e28 100644 --- a/docs/content/en/functions/strings/Substr.md +++ b/docs/content/en/functions/strings/Substr.md @@ -1,21 +1,20 @@ --- title: strings.Substr -description: Extracts parts of a string from a specified character's position and returns the specified number of characters. +description: Returns a substring of the given string, beginning with the start position and ending after the given length. categories: [] keywords: [] action: aliases: [substr] - related: [] + related: + - functions/strings/SliceString returnType: string - signatures: ['strings.Substr STRING START [LENGTH]'] + signatures: ['strings.Substr STRING [START] [LENGTH]'] aliases: [/functions/substr] --- -It normally takes two argument: `start` and `length`. It can also take one argument: `start`, i.e. `length` is omitted, in which case the substring starting from start until the end of the string will be returned. +The start position is zero-based, where `0` represents the first character of the string. If START is not specified, the substring will begin at position `0`. Specify a negative START position to extract characters from the end of the string. -To extract characters from the end of the string, use a negative start number. - -If `length` is given and is negative, that number of characters will be omitted from the end of string. +If LENGTH is not specified, the substring will include all characters from the START position to the end of the string. If negative, that number of characters will be omitted from the end of string. ```go-html-template {{ substr "abcdef" 0 }} → abcdef diff --git a/docs/content/en/functions/strings/Trim.md b/docs/content/en/functions/strings/Trim.md index 6dfac024b..9a87ff206 100644 --- a/docs/content/en/functions/strings/Trim.md +++ b/docs/content/en/functions/strings/Trim.md @@ -32,7 +32,7 @@ To remove leading and trailing newline characters and carriage returns: The `strings.Trim` function is commonly used in shortcodes to remove leading and trailing newlines characters and carriage returns from the content within the opening and closing shortcode tags. -For example, with this markdown: +For example, with this Markdown: ```text {{}} diff --git a/docs/content/en/functions/strings/Truncate.md b/docs/content/en/functions/strings/Truncate.md index 17ae0afc6..2e7693eb5 100644 --- a/docs/content/en/functions/strings/Truncate.md +++ b/docs/content/en/functions/strings/Truncate.md @@ -20,5 +20,5 @@ Since Go templates are HTML-aware, `truncate` will intelligently handle normal s {{% note %}} If you have a raw string that contains HTML tags you want to remain treated as HTML, you will need to convert the string to HTML using the [`safeHTML`]function before sending the value to `truncate`. Otherwise, the HTML tags will be escaped when passed through the `truncate` function. -[`safeHTML`]: /functions/safe/html +[`safeHTML`]: /functions/safe/html/ {{% /note %}} diff --git a/docs/content/en/functions/time/Duration.md b/docs/content/en/functions/time/Duration.md index f9c26d294..051be7ade 100644 --- a/docs/content/en/functions/time/Duration.md +++ b/docs/content/en/functions/time/Duration.md @@ -43,4 +43,4 @@ microseconds|`microsecond`, `us`, `µs` nanoseconds|`nanosecond`, `ns` [`time.Duration`]: https://pkg.go.dev/time#Duration -[methods]: /methods/duration +[methods]: /methods/duration/ diff --git a/docs/content/en/functions/time/Now.md b/docs/content/en/functions/time/Now.md index 60e45a91c..28ac7acfc 100644 --- a/docs/content/en/functions/time/Now.md +++ b/docs/content/en/functions/time/Now.md @@ -43,6 +43,6 @@ The `time.Now` function returns a `time.Time` value, so you can chain any of the {{ time.Now.Unix }} → 1697400955 (int64) ``` -[`time.Format`]: /functions/time/format +[`time.Format`]: /functions/time/format/ [localize]: /getting-started/glossary/#localization [time methods]: /methods/time/ diff --git a/docs/content/en/functions/time/ParseDuration.md b/docs/content/en/functions/time/ParseDuration.md index 091914132..d3369b899 100644 --- a/docs/content/en/functions/time/ParseDuration.md +++ b/docs/content/en/functions/time/ParseDuration.md @@ -34,4 +34,4 @@ There are 86400 seconds in one day. ``` [`time.Duration`]: https://pkg.go.dev/time#Duration -[methods]: /methods/duration +[methods]: /methods/duration/ diff --git a/docs/content/en/functions/time/_common/_index.md b/docs/content/en/functions/time/_common/_index.md index 47d5812fb..4328d4d14 100644 --- a/docs/content/en/functions/time/_common/_index.md +++ b/docs/content/en/functions/time/_common/_index.md @@ -7,7 +7,7 @@ cascade: --- diff --git a/docs/content/en/functions/transform/HTMLUnescape.md b/docs/content/en/functions/transform/HTMLUnescape.md index 180318077..1c88de672 100644 --- a/docs/content/en/functions/transform/HTMLUnescape.md +++ b/docs/content/en/functions/transform/HTMLUnescape.md @@ -25,6 +25,6 @@ In most contexts Go's [html/template] package will escape special characters. To {{ htmlUnescape "Lilo & Stitch" | safeHTML }} ``` -[`safehtml`]: /functions/safe/html +[`safehtml`]: /functions/safe/html/ [html entities]: https://developer.mozilla.org/en-us/docs/glossary/entity [html/template]: https://pkg.go.dev/html/template diff --git a/docs/content/en/functions/transform/Markdownify.md b/docs/content/en/functions/transform/Markdownify.md index 8fb1e48ce..7a84f43b7 100644 --- a/docs/content/en/functions/transform/Markdownify.md +++ b/docs/content/en/functions/transform/Markdownify.md @@ -1,6 +1,6 @@ --- title: transform.Markdownify -description: Renders markdown to HTML. +description: Renders Markdown to HTML. categories: [] keywords: [] action: @@ -24,8 +24,8 @@ To keep the wrapping `p` tags for a single paragraph, use the [`RenderString`] m [`RenderString`]: /methods/page/renderstring/ {{% note %}} -Although the `markdownify` function honors [markdown render hooks] when rendering markdown to HTML, use the `RenderString` method instead of `markdownify` if a render hook accesses `.Page` context. See issue [#9692] for details. +Although the `markdownify` function honors [Markdown render hooks] when rendering Markdown to HTML, use the `RenderString` method instead of `markdownify` if a render hook accesses `.Page` context. See issue [#9692] for details. -[markdown render hooks]: /templates/render-hooks/ +[Markdown render hooks]: /render-hooks/ [#9692]: https://github.com/gohugoio/hugo/issues/9692 {{% /note %}} diff --git a/docs/content/en/functions/transform/Unmarshal.md b/docs/content/en/functions/transform/Unmarshal.md index bc2b663e3..998152eb2 100644 --- a/docs/content/en/functions/transform/Unmarshal.md +++ b/docs/content/en/functions/transform/Unmarshal.md @@ -46,10 +46,10 @@ assets/ ``` ```go-html-template -{{ $data := "" }} +{{ $data := dict }} {{ $path := "data/books.json" }} {{ with resources.Get $path }} - {{ with unmarshal . }} + {{ with . | transform.Unmarshal }} {{ $data = . }} {{ end }} {{ else }} @@ -75,10 +75,10 @@ content/ ``` ```go-html-template -{{ $data := "" }} +{{ $data := dict }} {{ $path := "books.json" }} {{ with .Resources.Get $path }} - {{ with unmarshal . }} + {{ with . | transform.Unmarshal }} {{ $data = . }} {{ end }} {{ else }} @@ -95,7 +95,7 @@ content/ A remote resource is a file on a remote server, accessible via HTTP or HTTPS. ```go-html-template -{{ $data := "" }} +{{ $data := dict }} {{ $url := "https://example.org/books.json" }} {{ with resources.GetRemote $url }} {{ with .Err }} @@ -112,8 +112,15 @@ A remote resource is a file on a remote server, accessible via HTTP or HTTPS. {{ end }} ``` -[resource]: /getting-started/glossary/#resource -[page bundle]: /content-management/page-bundles +{{% note %}} +When retrieving remote data, a misconfigured server may send a response header with an incorrect [Content-Type]. For example, the server may set the Content-Type header to `application/octet-stream` instead of `application/json`. + +In these cases, pass the resource `Content` through the `transform.Unmarshal` function instead of passing the resource itself. For example, in the above, do this instead: + +`{{ $data = .Content | transform.Unmarshal }}` + +[Content-Type]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type +{{% /note %}} ## Options @@ -166,7 +173,7 @@ When unmarshaling an XML file, do not include the root node when accessing data. Get the remote data: ```go-html-template -{{ $data := "" }} +{{ $data := dict }} {{ $url := "https://example.org/books/index.xml" }} {{ with resources.GetRemote $url }} {{ with .Err }} @@ -182,7 +189,7 @@ Get the remote data: Inspect the data structure: ```go-html-template -{{ jsonify (dict "indent" " ") $data }}
+{{ debug.Dump $data }}
```
List the book titles:
@@ -245,7 +252,7 @@ Let's add a `lang` attribute to the `title` nodes of our RSS feed, and a namespa
After retrieving the remote data, inspect the data structure:
```go-html-template
-{{ jsonify (dict "indent" " ") $data }}
+{{ debug.Dump $data }}
```
Each item node looks like this:
@@ -288,5 +295,7 @@ Hugo renders this to:
```
-[`index`]: /functions/collections/indexfunction
+[`index`]: /functions/collections/indexfunction/
[identifiers]: https://go.dev/ref/spec#Identifiers
+[resource]: /getting-started/glossary/#resource
+[page bundle]: /content-management/page-bundles/
diff --git a/docs/content/en/functions/urls/AbsLangURL.md b/docs/content/en/functions/urls/AbsLangURL.md
index 876552bb7..67e1781e7 100644
--- a/docs/content/en/functions/urls/AbsLangURL.md
+++ b/docs/content/en/functions/urls/AbsLangURL.md
@@ -20,48 +20,44 @@ Use this function with both monolingual and multilingual configurations. The URL
- The `baseURL` in site configuration
- The language prefix, if any
-In examples that follow, the project is multilingual with content in both Español (`es`) and English (`en`). The default language is Español. The returned values are from the English site.
+In examples that follow, the project is multilingual with content in both English (`en`) and Spanish (`es`). The returned values are from the English site.
### Input does not begin with a slash
-If the input does not begin with a slash, the resulting URL will be correct regardless of the `baseURL`.
+If the input does not begin with a slash, the path in the resulting URL will be relative to the `baseURL` in your site configuration.
With `baseURL = https://example.org/`
```go-html-template
-{{ absLangURL "" }} → https://example.org/en/
-{{ absLangURL "articles" }} → https://example.org/en/articles
-{{ absLangURL "style.css" }} → https://example.org/en/style.css
+{{ absLangURL "" }} → https://example.org/en/
+{{ absLangURL "articles" }} → https://example.org/en/articles
+{{ absLangURL "style.css" }} → https://example.org/en/style.css
```
With `baseURL = https://example.org/docs/`
```go-html-template
-{{ absLangURL "" }} → https://example.org/docs/en/
-{{ absLangURL "articles" }} → https://example.org/docs/en/articles
-{{ absLangURL "style.css" }} → https://example.org/docs/en/style.css
+{{ absLangURL "" }} → https://example.org/docs/en/
+{{ absLangURL "articles" }} → https://example.org/docs/en/articles
+{{ absLangURL "style.css" }} → https://example.org/docs/en/style.css
```
### Input begins with a slash
-If the input begins with a slash, the resulting URL will be incorrect when the `baseURL` includes a subdirectory. With a leading slash, the function returns a URL relative to the protocol+host section of the `baseURL`.
+If the input begins with a slash, the path in the resulting URL will be relative to the protocol+host of the `baseURL` in your site configuration.
With `baseURL = https://example.org/`
```go-html-template
-{{ absLangURL "/" }} → https://example.org/en/
-{{ absLangURL "/articles" }} → https://example.org/en/articles
-{{ absLangURL "/style.css" }} → https://example.org/en/style.css
+{{ absLangURL "/" }} → https://example.org/en/
+{{ absLangURL "/articles" }} → https://example.org/en/articles
+{{ absLangURL "/style.css" }} → https://example.org/en/style.css
```
With `baseURL = https://example.org/docs/`
```go-html-template
-{{ absLangURL "/" }} → https://example.org/en/
-{{ absLangURL "/articles" }} → https://example.org/en/articles
-{{ absLangURL "/style.css" }} → https://example.org/en/style.css
+{{ absLangURL "/" }} → https://example.org/en/
+{{ absLangURL "/articles" }} → https://example.org/en/articles
+{{ absLangURL "/style.css" }} → https://example.org/en/style.css
```
-
-{{% note %}}
-The last three examples are not desirable in most situations. As a best practice, never include a leading slash when using this function.
-{{% /note %}}
diff --git a/docs/content/en/functions/urls/AbsURL.md b/docs/content/en/functions/urls/AbsURL.md
index 5b027ae84..1120eac42 100644
--- a/docs/content/en/functions/urls/AbsURL.md
+++ b/docs/content/en/functions/urls/AbsURL.md
@@ -14,53 +14,49 @@ action:
aliases: [/functions/absurl]
---
-With multilingual configurations, use the [`absLangURL`] function instead. The URL returned by this function depends on:
+With multilingual configurations, use the [`urls.AbsLangURL`] function instead. The URL returned by this function depends on:
- Whether the input begins with a slash
- The `baseURL` in site configuration
### Input does not begin with a slash
-If the input does not begin with a slash, the resulting URL will be correct regardless of the `baseURL`.
+If the input does not begin with a slash, the path in the resulting URL will be relative to the `baseURL` in your site configuration.
With `baseURL = https://example.org/`
```go-html-template
-{{ absURL "" }} → https://example.org/
-{{ absURL "articles" }} → https://example.org/articles
-{{ absURL "style.css" }} → https://example.org/style.css
+{{ absURL "" }} → https://example.org/
+{{ absURL "articles" }} → https://example.org/articles
+{{ absURL "style.css" }} → https://example.org/style.css
```
With `baseURL = https://example.org/docs/`
```go-html-template
-{{ absURL "" }} → https://example.org/docs/
-{{ absURL "articles" }} → https://example.org/docs/articles
-{{ absURL "style.css" }} → https://example.org/docs/style.css
+{{ absURL "" }} → https://example.org/docs/
+{{ absURL "articles" }} → https://example.org/docs/articles
+{{ absURL "style.css" }} → https://example.org/docs/style.css
```
#### Input begins with a slash
-If the input begins with a slash, the resulting URL will be incorrect when the `baseURL` includes a subdirectory. With a leading slash, the function returns a URL relative to the protocol+host section of the `baseURL`.
+If the input begins with a slash, the path in the resulting URL will be relative to the protocol+host of the `baseURL` in your site configuration.
With `baseURL = https://example.org/`
```go-html-template
-{{ absURL "/" }} → https://example.org/
-{{ absURL "/articles" }} → https://example.org/articles
-{{ absURL "/style.css" }} → https://example.org/style.css
+{{ absURL "/" }} → https://example.org/
+{{ absURL "/articles" }} → https://example.org/articles
+{{ absURL "/style.css" }} → https://example.org/style.css
```
With `baseURL = https://example.org/docs/`
```go-html-template
-{{ absURL "/" }} → https://example.org/
-{{ absURL "/articles" }} → https://example.org/articles
-{{ absURL "/style.css" }} → https://example.org/style.css
+{{ absURL "/" }} → https://example.org/
+{{ absURL "/articles" }} → https://example.org/articles
+{{ absURL "/style.css" }} → https://example.org/style.css
```
-{{% note %}}
-The last three examples are not desirable in most situations. As a best practice, never include a leading slash when using this function.
-{{% /note %}}
-
-[`absLangURL`]: /functions/urls/abslangurl/
+[`urls.AbsLangURL`]: /functions/urls/abslangurl/
diff --git a/docs/content/en/functions/urls/Anchorize.md b/docs/content/en/functions/urls/Anchorize.md
index 72b3d54a9..f3939675a 100644
--- a/docs/content/en/functions/urls/Anchorize.md
+++ b/docs/content/en/functions/urls/Anchorize.md
@@ -16,14 +16,14 @@ aliases: [/functions/anchorize]
## Sanitizing logic
-With the default markdown renderer, Goldmark, the sanitizing logic is controlled by your site configuration:
+With the default Markdown renderer, Goldmark, the sanitizing logic is controlled by your site configuration:
{{< code-toggle file=hugo >}}
[markup.goldmark.parser]
autoHeadingIDType = 'github'
{{< /code-toggle >}}
-This controls the behavior of the `anchorize` function and the generation of heading IDs when rendering markdown to HTML.
+This controls the behavior of the `anchorize` function and the generation of heading IDs when rendering Markdown to HTML.
Set `autoHeadingIDType` to one of:
diff --git a/docs/content/en/functions/urls/JoinPath.md b/docs/content/en/functions/urls/JoinPath.md
index 7acecb506..d9822cfda 100644
--- a/docs/content/en/functions/urls/JoinPath.md
+++ b/docs/content/en/functions/urls/JoinPath.md
@@ -27,4 +27,4 @@ aliases: [/functions/urls.joinpath]
Unlike the [`path.Join`] function, `urls.JoinPath` retains consecutive leading slashes.
-[`path.Join`]: /functions/path/join
+[`path.Join`]: /functions/path/join/
diff --git a/docs/content/en/functions/urls/Parse.md b/docs/content/en/functions/urls/Parse.md
index 2eb4eeadf..a64116254 100644
--- a/docs/content/en/functions/urls/Parse.md
+++ b/docs/content/en/functions/urls/Parse.md
@@ -19,6 +19,7 @@ The `urls.Parse` function parses a URL into a [URL structure](https://godoc.org/
{{ $url := "https://example.org:123/foo?a=6&b=7#bar" }}
{{ $u := urls.Parse $url }}
+{{ $u.String }} → https://example.org:123/foo?a=6&b=7#bar
{{ $u.IsAbs }} → true
{{ $u.Scheme }} → https
{{ $u.Host }} → example.org:123
diff --git a/docs/content/en/functions/urls/RelLangURL.md b/docs/content/en/functions/urls/RelLangURL.md
index 2c1037038..883e7dda2 100644
--- a/docs/content/en/functions/urls/RelLangURL.md
+++ b/docs/content/en/functions/urls/RelLangURL.md
@@ -17,51 +17,49 @@ aliases: [/functions/rellangurl]
Use this function with both monolingual and multilingual configurations. The URL returned by this function depends on:
- Whether the input begins with a slash
-- The `baseURL` in site configuration
+- The `baseURL` in your site configuration
- The language prefix, if any
-In examples that follow, the project is multilingual with content in both Español (`es`) and English (`en`). The default language is Español. The returned values are from the English site.
+In examples that follow, the project is multilingual with content in both English (`en`) and Spanish (`es`). The returned values are from the English site.
### Input does not begin with a slash
-If the input does not begin with a slash, the resulting URL will be correct regardless of the `baseURL`.
+If the input does not begin with a slash, the resulting URL will be relative to the `baseURL` in your site configuration.
With `baseURL = https://example.org/`
```go-html-template
-{{ relLangURL "" }} → /en/
-{{ relLangURL "articles" }} → /en/articles
-{{ relLangURL "style.css" }} → /en/style.css
+{{ relLangURL "" }} → /en/
+{{ relLangURL "articles" }} → /en/articles
+{{ relLangURL "style.css" }} → /en/style.css
+{{ relLangURL "https://example.org/foo" }} → /en/foo
```
With `baseURL = https://example.org/docs/`
```go-html-template
-{{ relLangURL "" }} → /docs/en/
-{{ relLangURL "articles" }} → /docs/en/articles
-{{ relLangURL "style.css" }} → /docs/en/style.css
+{{ relLangURL "" }} → /docs/en/
+{{ relLangURL "articles" }} → /docs/en/articles
+{{ relLangURL "style.css" }} → /docs/en/style.css
+{{ relLangURL "https://example.org/docs/foo" }} → /docs/en/foo
```
#### Input begins with a slash
-If the input begins with a slash, the resulting URL will be incorrect when the `baseURL` includes a subdirectory. With a leading slash, the function returns a URL relative to the protocol+host section of the `baseURL`.
+If the input begins with a slash, the resulting URL will be relative to the protocol+host of the `baseURL` in your site configuration.
With `baseURL = https://example.org/`
```go-html-template
-{{ relLangURL "/" }} → /en/
-{{ relLangURL "/articles" }} → /en/articles
-{{ relLangURL "/style.css" }} → /en/style.css
+{{ relLangURL "/" }} → /en/
+{{ relLangURL "/articles" }} → /en/articles
+{{ relLangURL "/style.css" }} → /en/style.css
```
With `baseURL = https://example.org/docs/`
```go-html-template
-{{ relLangURL "/" }} → /en/
-{{ relLangURL "/articles" }} → /en/articles
-{{ relLangURL "/style.css" }} → /en/style.css
+{{ relLangURL "/" }} → /en/
+{{ relLangURL "/articles" }} → /en/articles
+{{ relLangURL "/style.css" }} → /en/style.css
```
-
-{{% note %}}
-The last three examples are not desirable in most situations. As a best practice, never include a leading slash when using this function.
-{{% /note %}}
diff --git a/docs/content/en/functions/urls/RelURL.md b/docs/content/en/functions/urls/RelURL.md
index 9320c2827..18ac24d10 100644
--- a/docs/content/en/functions/urls/RelURL.md
+++ b/docs/content/en/functions/urls/RelURL.md
@@ -14,53 +14,51 @@ action:
aliases: [/functions/relurl]
---
-With multilingual configurations, use the [`relLangURL`] function instead. The URL returned by this function depends on:
+With multilingual configurations, use the [`urls.RelLangURL`] function instead. The URL returned by this function depends on:
- Whether the input begins with a slash
-- The `baseURL` in site configuration
+- The `baseURL` in your site configuration
### Input does not begin with a slash
-If the input does not begin with a slash, the resulting URL will be correct regardless of the `baseURL`.
+If the input does not begin with a slash, the resulting URL will be relative to the `baseURL` in your site configuration.
With `baseURL = https://example.org/`
```go-html-template
-{{ relURL "" }} → /
-{{ relURL "articles" }} → /articles
-{{ relURL "style.css" }} → /style.css
+{{ relURL "" }} → /
+{{ relURL "articles" }} → /articles
+{{ relURL "style.css" }} → /style.css
+{{ relURL "https://example.org/foo" }} → /foo
```
With `baseURL = https://example.org/docs/`
```go-html-template
-{{ relURL "" }} → /docs/
-{{ relURL "articles" }} → /docs/articles
-{{ relURL "style.css" }} → /docs/style.css
+{{ relURL "" }} → /docs/
+{{ relURL "articles" }} → /docs/articles
+{{ relURL "style.css" }} → /docs/style.css
+{{ relURL "https://example.org/docs/foo" }} → /docs/foo
```
#### Input begins with a slash
-If the input begins with a slash, the resulting URL will be incorrect when the `baseURL` includes a subdirectory. With a leading slash, the function returns a URL relative to the protocol+host section of the `baseURL`.
+If the input begins with a slash, the resulting URL will be relative to the protocol+host of the `baseURL` in your site configuration.
With `baseURL = https://example.org/`
```go-html-template
-{{ relURL "/" }} → /
-{{ relURL "/articles" }} → /articles
-{{ relURL "style.css" }} → /style.css
+{{ relURL "/" }} → /
+{{ relURL "/articles" }} → /articles
+{{ relURL "/style.css" }} → /style.css
```
With `baseURL = https://example.org/docs/`
```go-html-template
-{{ relURL "/" }} → /
-{{ relURL "/articles" }} → /articles
-{{ relURL "/style.css" }} → /style.css
+{{ relURL "/" }} → /
+{{ relURL "/articles" }} → /articles
+{{ relURL "/style.css" }} → /style.css
```
-{{% note %}}
-The last three examples are not desirable in most situations. As a best practice, never include a leading slash when using this function.
-{{% /note %}}
-
-[`relLangURL`]: /functions/urls/rellangurl/
+[`urls.RelLangURL`]: /functions/urls/rellangurl/
diff --git a/docs/content/en/functions/urls/_common/_index.md b/docs/content/en/functions/urls/_common/_index.md
index 47d5812fb..4328d4d14 100644
--- a/docs/content/en/functions/urls/_common/_index.md
+++ b/docs/content/en/functions/urls/_common/_index.md
@@ -7,7 +7,7 @@ cascade:
---
diff --git a/docs/content/en/functions/urls/_common/anchorize-vs-urlize.md b/docs/content/en/functions/urls/_common/anchorize-vs-urlize.md
index 0f01bcf78..718c14098 100644
--- a/docs/content/en/functions/urls/_common/anchorize-vs-urlize.md
+++ b/docs/content/en/functions/urls/_common/anchorize-vs-urlize.md
@@ -4,8 +4,8 @@
The [`anchorize`] and [`urlize`] functions are similar:
-[`anchorize`]: /functions/urls/anchorize
-[`urlize`]: /functions/urls/urlize
+[`anchorize`]: /functions/urls/anchorize/
+[`urlize`]: /functions/urls/urlize/
- Use the `anchorize` function to generate an HTML `id` attribute value
- Use the `urlize` function to sanitize a string for usage in a URL
diff --git a/docs/content/en/getting-started/_index.md b/docs/content/en/getting-started/_index.md
index 780b96a62..1648f0224 100644
--- a/docs/content/en/getting-started/_index.md
+++ b/docs/content/en/getting-started/_index.md
@@ -1,12 +1,12 @@
---
title: Getting started
-linkTitle: Overview
+linkTitle: In this section
description: Quick start and guides for installing Hugo on your preferred operating system.
categories: []
keywords: []
menu:
docs:
- identifier: getting-started-overview
+ identifier: getting-started-in-this-section
parent: getting-started
weight: 10
weight: 10
diff --git a/docs/content/en/getting-started/configuration-markup.md b/docs/content/en/getting-started/configuration-markup.md
index 607301d3a..ab3dfa221 100644
--- a/docs/content/en/getting-started/configuration-markup.md
+++ b/docs/content/en/getting-started/configuration-markup.md
@@ -2,7 +2,7 @@
title: Configure markup
description: Configure rendering of markup to HTML.
categories: [getting started,fundamentals]
-keywords: [configuration,highlighting]
+keywords: [markup,markdown,goldmark,asciidoc,asciidoctor,highlighting]
menu:
docs:
parent: getting-started
@@ -14,16 +14,16 @@ toc: true
## Default handler
-By default, Hugo uses [Goldmark] to render markdown to HTML.
+Hugo uses [Goldmark] to render Markdown to HTML.
{{< code-toggle file=hugo >}}
[markup]
defaultMarkdownHandler = 'goldmark'
{{< /code-toggle >}}
-Files with the `.md` or `.markdown` extension are processed as markdown, provided that you have not specified a different [content format] using the `markup` field in front matter.
+Files with the `.md` or `.markdown` extension are processed as Markdown, provided that you have not specified a different [content format] using the `markup` field in front matter.
-To use a different renderer for markdown files, specify one of `asciidocext`, `org`, `pandoc`, or `rst` in your site configuration.
+To use a different renderer for Markdown files, specify one of `asciidocext`, `org`, `pandoc`, or `rst` in your site configuration.
defaultMarkdownHandler|Description
:--|:--
@@ -33,41 +33,86 @@ defaultMarkdownHandler|Description
`pandoc`|[Pandoc]
`rst`|[reStructuredText]
-To use Asciidoc, Pandoc, or reStructuredText you must install the relevant renderer and update your [security policy].
+To use AsciiDoc, Pandoc, or reStructuredText you must install the relevant renderer and update your [security policy].
{{% note %}}
-Unless you need a unique capability provided by one of the alternate markdown handlers, we strongly recommend that you use the default setting. Goldmark is fast, well maintained, conforms to the [CommonMark] specification, and is compatible with [GitHub Flavored Markdown] (GFM).
+Unless you need a unique capability provided by one of the alternate Markdown handlers, we strongly recommend that you use the default setting. Goldmark is fast, well maintained, conforms to the [CommonMark] specification, and is compatible with [GitHub Flavored Markdown] (GFM).
[commonmark]: https://spec.commonmark.org/0.30/
[github flavored markdown]: https://github.github.com/gfm/
{{% /note %}}
[asciidoc]: https://asciidoc.org/
-[content format]: /content-management/formats/#list-of-content-formats
+[content format]: /content-management/formats/#formats
[emacs org mode]: https://orgmode.org/
[goldmark]: https://github.com/yuin/goldmark/
[pandoc]: https://pandoc.org/
[restructuredtext]: https://docutils.sourceforge.io/rst.html
-[security policy]: /about/security-model/#security-policy
+[security policy]: /about/security/#security-policy
## Goldmark
-This is the default configuration for the Goldmark markdown renderer:
+This is the default configuration for the Goldmark Markdown renderer:
{{< code-toggle config=markup.goldmark />}}
-For details on the extensions, refer to the [Goldmark documentation](https://github.com/yuin/goldmark/#built-in-extensions).
+### Goldmark extensions
-Some settings explained:
+The extensions below, excluding Extras and Passthrough, are enabled by default.
-hardWraps
-: By default, Goldmark ignores newlines within a paragraph. Set to `true` to render newlines as `{{ .Fragments.Headings | jsonify (dict "indent" " ") }}
+{{ debug.Dump .Fragments.Headings }}
```
HeadingsMap
: (`slice`) A slice of maps of all headings on the page, with first-level keys for each heading. Each map contains the following keys: `ID`, `Level`, `Title` and `Headings`. To inspect the data structure:
```go-html-template
-{{ .Fragments.HeadingsMap | jsonify (dict "indent" " ") }}
+{{ debug.Dump .Fragments.HeadingsMap }}
```
Identifiers
: (`slice`) A slice containing the `id` of each heading on the page. To inspect the data structure:
```go-html-template
-{{ .Fragments.Identifiers | jsonify (dict "indent" " ") }}
+{{ debug.Dump .Fragments.Identifiers }}
```
Identifiers.Contains ID
@@ -100,7 +100,7 @@ When using the `Fragments` methods within a shortcode, call the shortcode using
[fragment]: /getting-started/glossary/#fragment
[markdown attribute]: /getting-started/glossary/#markdown-attribute
[setext]: https://spec.commonmark.org/0.30/#setext-headings
-[table of contents]: /methods/page/tableofcontents
+[table of contents]: /methods/page/tableofcontents/
[walking]: /getting-started/glossary/#walk
-[`tableofcontents`]: /methods/page/tableofcontents
+[`tableofcontents`]: /methods/page/tableofcontents/
[render hook]: /getting-started/glossary/#render-hook
diff --git a/docs/content/en/methods/page/FuzzyWordCount.md b/docs/content/en/methods/page/FuzzyWordCount.md
index 600ad48d5..8523edf8c 100644
--- a/docs/content/en/methods/page/FuzzyWordCount.md
+++ b/docs/content/en/methods/page/FuzzyWordCount.md
@@ -17,4 +17,4 @@ action:
To get the exact word count, use the [`WordCount`] method.
-[`WordCount`]: /methods/page/wordcount
+[`WordCount`]: /methods/page/wordcount/
diff --git a/docs/content/en/methods/page/GetPage.md b/docs/content/en/methods/page/GetPage.md
index b1f192d58..9b4ced345 100644
--- a/docs/content/en/methods/page/GetPage.md
+++ b/docs/content/en/methods/page/GetPage.md
@@ -13,7 +13,7 @@ aliases: [/functions/getpage]
The `GetPage` method is also available on a `Site` object. See [details].
-[details]: /methods/site/getpage
+[details]: /methods/site/getpage/
When using the `GetPage` method on the `Page` object, specify a path relative to the current directory or relative to the content directory.
@@ -36,7 +36,7 @@ content/
└── _index.md
```
-The examples below depict the result of rendering works/paintings/the-mona-list.md with a single page template:
+The examples below depict the result of rendering works/paintings/the-mona-lisa.md with a single page template:
```go-html-template
{{ with .GetPage "starry-night" }}
diff --git a/docs/content/en/methods/page/HeadingsFiltered.md b/docs/content/en/methods/page/HeadingsFiltered.md
index a39c48da1..d741b57ce 100644
--- a/docs/content/en/methods/page/HeadingsFiltered.md
+++ b/docs/content/en/methods/page/HeadingsFiltered.md
@@ -14,5 +14,5 @@ action:
Use in conjunction with the [`Related`] method on a [`Pages`] object. See [details].
[`Pages`]: /methods/pages/
-[`Related`]: /methods/pages/related
+[`Related`]: /methods/pages/related/
[details]: /content-management/related/#index-content-headings-in-related-content
diff --git a/docs/content/en/methods/page/InSection.md b/docs/content/en/methods/page/InSection.md
index b98fbc808..41ce918f3 100644
--- a/docs/content/en/methods/page/InSection.md
+++ b/docs/content/en/methods/page/InSection.md
@@ -98,5 +98,5 @@ Gaining a thorough understanding of context is critical for anyone writing templ
{{% /note %}}
[context]: /getting-started/glossary/#context
-[`with`]: /functions/go-template/with
-[`else`]: /functions/go-template/else
+[`with`]: /functions/go-template/with/
+[`else`]: /functions/go-template/else/
diff --git a/docs/content/en/methods/page/IsAncestor.md b/docs/content/en/methods/page/IsAncestor.md
index ca23c0868..8ace8463c 100644
--- a/docs/content/en/methods/page/IsAncestor.md
+++ b/docs/content/en/methods/page/IsAncestor.md
@@ -1,6 +1,6 @@
---
title: IsAncestor
-description: Reports whether PAGE1 in an ancestor of PAGE2.
+description: Reports whether PAGE1 is an ancestor of PAGE2.
categories: []
keywords: []
action:
@@ -96,5 +96,5 @@ Gaining a thorough understanding of context is critical for anyone writing templ
{{% /note %}}
[context]: /getting-started/glossary/#context
-[`with`]: /functions/go-template/with
-[`else`]: /functions/go-template/else
+[`with`]: /functions/go-template/with/
+[`else`]: /functions/go-template/else/
diff --git a/docs/content/en/methods/page/IsDescendant.md b/docs/content/en/methods/page/IsDescendant.md
index f1042564e..2c0599d91 100644
--- a/docs/content/en/methods/page/IsDescendant.md
+++ b/docs/content/en/methods/page/IsDescendant.md
@@ -1,6 +1,6 @@
---
title: IsDescendant
-description: Reports whether PAGE1 in a descendant of PAGE2.
+description: Reports whether PAGE1 is a descendant of PAGE2.
categories: []
keywords: []
action:
@@ -95,5 +95,5 @@ Gaining a thorough understanding of context is critical for anyone writing templ
{{% /note %}}
[context]: /getting-started/glossary/#context
-[`with`]: /functions/go-template/with
-[`else`]: /functions/go-template/else
+[`with`]: /functions/go-template/with/
+[`else`]: /functions/go-template/else/
diff --git a/docs/content/en/methods/page/Keywords.md b/docs/content/en/methods/page/Keywords.md
index 5ad37ce51..ef68c27f5 100644
--- a/docs/content/en/methods/page/Keywords.md
+++ b/docs/content/en/methods/page/Keywords.md
@@ -11,7 +11,7 @@ action:
By default, Hugo evaluates the keywords when creating collections of [related content].
-[related content]: /content-management/related
+[related content]: /content-management/related/
{{< code-toggle file=content/recipes/sushi.md fm=true >}}
title = 'How to make spicy tuna hand rolls'
@@ -32,7 +32,7 @@ Or use the [delimit] function:
{{ delimit .Keywords ", " ", and " }} → tuna, sriracha, nori, and rice
```
-[delimit]: /functions/collections/delimit
+[delimit]: /functions/collections/delimit/
Keywords are also a useful [taxonomy]:
@@ -43,4 +43,4 @@ keyword = 'keywords'
category = 'categories'
{{< /code-toggle >}}
-[taxonomy]: /content-management/taxonomies
+[taxonomy]: /content-management/taxonomies/
diff --git a/docs/content/en/methods/page/Language.md b/docs/content/en/methods/page/Language.md
index 4e65107da..321b44e56 100644
--- a/docs/content/en/methods/page/Language.md
+++ b/docs/content/en/methods/page/Language.md
@@ -34,7 +34,7 @@ Lang
```
LanguageCode
-: (`string`) The language code from the site configuration.
+: (`string`) The language code from the site configuration. Falls back to `Lang` if not defined.
```go-html-template
{{ .Language.LanguageCode }} → de-DE
@@ -61,5 +61,5 @@ Weight
{{ .Language.Weight }} → 2
```
-[details]: /methods/site/language
+[details]: /methods/site/language/
[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646
diff --git a/docs/content/en/methods/page/Lastmod.md b/docs/content/en/methods/page/Lastmod.md
index c1692233d..78760d556 100644
--- a/docs/content/en/methods/page/Lastmod.md
+++ b/docs/content/en/methods/page/Lastmod.md
@@ -33,8 +33,8 @@ In the example above we explicitly set the last modification date in front matte
Learn more about [date configuration].
-[`gitinfo`]: /methods/page/gitinfo
-[`time.format`]: /functions/time/format
+[`gitinfo`]: /methods/page/gitinfo/
+[`time.format`]: /functions/time/format/
[date configuration]: /getting-started/configuration/#configure-dates
-[time methods]: /methods/time
+[time methods]: /methods/time/
[time.time]: https://pkg.go.dev/time#time
diff --git a/docs/content/en/methods/page/LinkTitle.md b/docs/content/en/methods/page/LinkTitle.md
index 746e433bb..0ce32e641 100644
--- a/docs/content/en/methods/page/LinkTitle.md
+++ b/docs/content/en/methods/page/LinkTitle.md
@@ -12,7 +12,7 @@ action:
The `LinkTitle` method returns the `linkTitle` field as defined in front matter, falling back to the value returned by the [`Title`] method.
-[`Title`]: /methods/page/title
+[`Title`]: /methods/page/title/
{{< code-toggle file=content/articles/healthy-desserts.md fm=true >}}
title = 'Seventeen delightful recipes for healthy desserts'
diff --git a/docs/content/en/methods/page/NextInSection.md b/docs/content/en/methods/page/NextInSection.md
index 73f82d754..59a35d03d 100644
--- a/docs/content/en/methods/page/NextInSection.md
+++ b/docs/content/en/methods/page/NextInSection.md
@@ -65,7 +65,7 @@ With the `PrevInSection` and `NextInSection` methods, the navigation sort order
For example, with a page collection sorted by title, the navigation sort order will use Hugo’s default sort order. This is probably not what you want or expect. For this reason, the Next and Prev methods on a Pages object are generally a better choice.
-[date]: /methods/page/date
-[weight]: /methods/page/weight
-[linkTitle]: /methods/page/linktitle
-[title]: /methods/page/title
+[date]: /methods/page/date/
+[weight]: /methods/page/weight/
+[linkTitle]: /methods/page/linktitle/
+[title]: /methods/page/title/
diff --git a/docs/content/en/methods/page/Pages.md b/docs/content/en/methods/page/Pages.md
index 2f329eeec..d446292e2 100644
--- a/docs/content/en/methods/page/Pages.md
+++ b/docs/content/en/methods/page/Pages.md
@@ -75,7 +75,7 @@ In the last example, the collection includes pages in the resources subdirectory
{{% note %}}
When used with a `Site` object, the `Pages` method recursively returns all pages within the site. See [details].
-[details]: /methods/site/pages
+[details]: /methods/site/pages/
{{% /note %}}
```go-html-template
diff --git a/docs/content/en/methods/page/Paginator.md b/docs/content/en/methods/page/Paginator.md
index b1540286a..b411e6ec0 100644
--- a/docs/content/en/methods/page/Paginator.md
+++ b/docs/content/en/methods/page/Paginator.md
@@ -28,7 +28,7 @@ Although simple to invoke, with the `Paginator` method you can neither filter no
The [`Paginate`] method is more flexible, and strongly recommended.
-[`paginate`]: /methods/page/paginate
+[`paginate`]: /methods/page/paginate/
{{% /note %}}
{{% note %}}
diff --git a/docs/content/en/methods/page/Param.md b/docs/content/en/methods/page/Param.md
index b2932d981..daf09a5b4 100644
--- a/docs/content/en/methods/page/Param.md
+++ b/docs/content/en/methods/page/Param.md
@@ -29,6 +29,7 @@ Content:
title = 'Example'
date = 2023-01-01
draft = false
+[params]
display_toc = false
{{< /code-toggle >}}
diff --git a/docs/content/en/methods/page/Params.md b/docs/content/en/methods/page/Params.md
index 13416ada7..219b5de9d 100644
--- a/docs/content/en/methods/page/Params.md
+++ b/docs/content/en/methods/page/Params.md
@@ -17,8 +17,9 @@ With this front matter:
{{< code-toggle file=content/news/annual-conference.md >}}
title = 'Annual conference'
date = 2023-10-17T15:11:37-07:00
+[params]
display_related = true
-[author]
+[params.author]
email = 'jsmith@example.org'
name = 'John Smith'
{{< /code-toggle >}}
@@ -38,6 +39,6 @@ In the template example above, each of the keys is a valid identifier. For examp
{{ index .Params "key-with-hyphens" }} → 2023
```
-[`index`]: /functions/collections/indexfunction
+[`index`]: /functions/collections/indexfunction/
[chaining]: /getting-started/glossary/#chain
[identifiers]: /getting-started/glossary/#identifier
diff --git a/docs/content/en/methods/page/Parent.md b/docs/content/en/methods/page/Parent.md
index 9d9ed7ea3..db01eb589 100644
--- a/docs/content/en/methods/page/Parent.md
+++ b/docs/content/en/methods/page/Parent.md
@@ -21,7 +21,7 @@ action:
{{% note %}}
The parent section of a regular page is the [current section].
-[current section]: /methods/page/currentsection
+[current section]: /methods/page/currentsection/
{{% /note %}}
Consider this content structure:
diff --git a/docs/content/en/methods/page/Path.md b/docs/content/en/methods/page/Path.md
new file mode 100644
index 000000000..b65120d4d
--- /dev/null
+++ b/docs/content/en/methods/page/Path.md
@@ -0,0 +1,157 @@
+---
+title: Path
+description: Returns the logical path of the given page.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/File
+ - methods/page/RelPermalink
+ returnType: string
+ signatures: [PAGE.Path]
+toc: true
+---
+
+{{< new-in 0.123.0 >}}
+
+The `Path` method on a `Page` object returns the logical path of the given page, regardless of whether the page is backed by a file.
+
+[logical path]: /getting-started/glossary#logical-path
+
+```go-html-template
+{{ .Path }} → /posts/post-1
+```
+
+This value is neither a file path nor a relative URL. It is a logical identifier for each page, independent of content format, language, and URL modifiers.
+
+{{% note %}}
+Beginning with the release of [v0.92.0] in January 2022, Hugo emitted a warning whenever calling the `Path` method. The warning indicated that this method would change in a future release.
+
+The meaning of, and value returned by, the `Path` method on a `Page` object changed with the release of [v0.123.0] in February 2024.
+
+[v0.92.0]: https://github.com/gohugoio/hugo/releases/tag/v0.92.0
+[v0.123.0]: https://github.com/gohugoio/hugo/releases/tag/v0.123.0
+{{% /note %}}
+
+To determine the logical path for pages backed by a file, Hugo starts with the file path, relative to the content directory, and then:
+
+1. Strips the file extension
+2. Strips the language identifier
+3. Converts the result to lower case
+4. Replaces spaces with hyphens
+
+The value returned by the `Path` method on a `Page` object is independent of content format, language, and URL modifiers such as the `slug` and `url` front matter fields.
+
+## Examples
+
+### Monolingual site
+
+Note that the logical path is independent of content format and URL modifiers.
+
+File path|Front matter slug|Logical path
+:--|:--|:--
+`content/_index.md`||`/`
+`content/posts/_index.md`||`/posts`
+`content/posts/post-1.md`|`foo`|`/posts/post-1`
+`content/posts/post-2.html`|`bar`|`/posts/post-2`
+
+### Multilingual site
+
+Note that the logical path is independent of content format, language identifiers, and URL modifiers.
+
+File path|Front matter slug|Logical path
+:--|:--|:--
+`content/_index.en.md`||`/`
+`content/_index.de.md`||`/`
+`content/posts/_index.en.md`||`/posts`
+`content/posts/_index.de.md`||`/posts`
+`content/posts/posts-1.en.md`|`foo`|`/posts/post-1`
+`content/posts/posts-1.de.md`|`foo`|`/posts/post-1`
+`content/posts/posts-2.en.html`|`bar`|`/posts/post-2`
+`content/posts/posts-2.de.html`|`bar`|`/posts/post-2`
+
+### Pages not backed by a file
+
+The `Path` method on a `Page` object returns a value regardless of whether the page is backed by a file.
+
+```text
+content/
+└── posts/
+ └── post-1.md <-- front matter: tags = ['hugo']
+```
+
+When you build the site:
+
+```text
+public/
+├── posts/
+│ ├── post-1/
+│ │ └── index.html .Page.Path = /posts/post-1
+│ └── index.html .Page.Path = /posts
+├── tags/
+│ ├── hugo/
+│ │ └── index.html .Page.Path = /tags/hugo
+│ └── index.html .Page.Path = /tags
+└── index.html .Page.Path = /
+```
+
+## Finding pages
+
+These methods, functions, and shortcodes use the logical path to find the given page:
+
+Methods|Functions|Shortcodes
+:--|:--|:--
+[`Site.GetPage`]|[`urls.Ref`]|[`ref`]
+[`Page.GetPage`]|[`urls.RelRef`]|[`relref`]
+[`Page.Ref`]||
+[`Page.RelRef`]||
+[`Shortcode.Ref`]||
+[`Shortcode.RelRef`]||
+
+[`urls.Ref`]: /functions/urls/ref/
+[`urls.RelRef`]: /functions/urls/relref/
+[`Page.GetPage`]: /methods/page/getpage/
+[`Site.GetPage`]: /methods/site/getpage/
+[`ref`]: /content-management/shortcodes/#ref
+[`relref`]: /content-management/shortcodes/#relref
+[`Page.Ref`]: /methods/page/ref/
+[`Page.RelRef`]: /methods/page/relref/
+[`Shortcode.Ref`]: /methods/shortcode/ref
+[`Shortcode.RelRef`]: /methods/shortcode/relref
+
+{{% note %}}
+Specify the logical path when using any of these methods, functions, or shortcodes. If you include a file extension or language identifier, Hugo will strip these values before finding the page in the logical tree.
+{{% /note %}}
+
+
+## Logical tree
+
+Just as file paths form a file tree, logical paths form a logical tree.
+
+A file tree:
+
+```text
+content/
+└── s1/
+ ├── p1/
+ │ └── index.md
+ └── p2.md
+```
+
+The same content represented as a logical tree:
+
+```text
+content/
+└── s1/
+ ├── p1
+ └── p2
+```
+
+A key difference between these trees is the relative path from p1 to p2:
+
+- In the file tree, the relative path from p1 to p2 is `../p2.md`
+- In the logical tree, the relative path is `p2`
+
+{{% note %}}
+Remember to use the logical path when using any of the methods, functions, or shortcodes listed in the previous section. If you include a file extension or language identifier, Hugo will strip these values before finding the page in the logical tree.
+{{% /note %}}
diff --git a/docs/content/en/methods/page/Plain.md b/docs/content/en/methods/page/Plain.md
index 6fdf60b62..3aae1ed61 100644
--- a/docs/content/en/methods/page/Plain.md
+++ b/docs/content/en/methods/page/Plain.md
@@ -13,7 +13,7 @@ action:
signatures: [PAGE.Plain]
---
-The `Plain` method on a `Page` object renders markdown and [shortcodes] to HTML, then strips the HTML [tags]. It does not strip HTML [entities]. The plain content does not include front matter.
+The `Plain` method on a `Page` object renders Markdown and [shortcodes] to HTML, then strips the HTML [tags]. It does not strip HTML [entities]. The plain content does not include front matter.
To prevent Go's [html/template] package from escaping HTML entities, pass the result through the [`htmlUnescape`] function.
@@ -25,4 +25,4 @@ To prevent Go's [html/template] package from escaping HTML entities, pass the re
[html/template]: https://pkg.go.dev/html/template
[entities]: https://developer.mozilla.org/en-US/docs/Glossary/Entity
[tags]: https://developer.mozilla.org/en-US/docs/Glossary/Tag
-[`htmlUnescape`]: /functions/
+[`htmlUnescape`]: /functions/transform/htmlunescape/
diff --git a/docs/content/en/methods/page/PlainWords.md b/docs/content/en/methods/page/PlainWords.md
index 4bc79d241..4f70193fe 100644
--- a/docs/content/en/methods/page/PlainWords.md
+++ b/docs/content/en/methods/page/PlainWords.md
@@ -15,7 +15,7 @@ action:
The `PlainWords` method on a `Page` object calls the [`Plain`] method, then uses Go's [`strings.Fields`] function to split the result into words.
{{% note %}}
-_Fields splits the string s around each instance of one or more consecutive white space characters, as defined by [`unicode.IsSpace`], returning a slice of substrings of s or an empty slice if s contains only white space._
+_Fields splits the string s around each instance of one or more consecutive whitespace characters, as defined by [`unicode.IsSpace`], returning a slice of substrings of s or an empty slice if s contains only whitespace._
[`unicode.IsSpace`]: https://pkg.go.dev/unicode#IsSpace
{{% /note %}}
@@ -32,5 +32,5 @@ To determine the approximate number of unique words on a page:
{{ .PlainWords | uniq }} → 42
```
-[`Plain`]: /methods/page/plain
+[`Plain`]: /methods/page/plain/
[`strings.Fields`]: https://pkg.go.dev/strings#Fields
diff --git a/docs/content/en/methods/page/PrevInSection.md b/docs/content/en/methods/page/PrevInSection.md
index c09e4580f..e6daf66c4 100644
--- a/docs/content/en/methods/page/PrevInSection.md
+++ b/docs/content/en/methods/page/PrevInSection.md
@@ -66,7 +66,7 @@ With the `PrevInSection` and `NextInSection` methods, the navigation sort order
For example, with a page collection sorted by title, the navigation sort order will use Hugo’s default sort order. This is probably not what you want or expect. For this reason, the Next and Prev methods on a Pages object are generally a better choice.
-[date]: /methods/page/date
-[weight]: /methods/page/weight
-[linkTitle]: /methods/page/linktitle
-[title]: /methods/page/title
+[date]: /methods/page/date/
+[weight]: /methods/page/weight/
+[linkTitle]: /methods/page/linktitle/
+[title]: /methods/page/title/
diff --git a/docs/content/en/methods/page/PublishDate.md b/docs/content/en/methods/page/PublishDate.md
index b1c0717a9..d1f2eb2a1 100644
--- a/docs/content/en/methods/page/PublishDate.md
+++ b/docs/content/en/methods/page/PublishDate.md
@@ -29,7 +29,7 @@ The publish date is a [time.Time] value. Format and localize the value with the
In the example above we explicitly set the publish date in front matter. With Hugo's default configuration, the `PublishDate` method returns the front matter value. This behavior is configurable, allowing you to set fallback values if the publish date is not defined in front matter. See [details].
-[`time.Format`]: /functions/time/format
+[`time.Format`]: /functions/time/format/
[details]: /getting-started/configuration/#configure-dates
-[time methods]: /methods/time
+[time methods]: /methods/time/
[time.Time]: https://pkg.go.dev/time#Time
diff --git a/docs/content/en/methods/page/RawContent.md b/docs/content/en/methods/page/RawContent.md
index 258a294d0..12686c695 100644
--- a/docs/content/en/methods/page/RawContent.md
+++ b/docs/content/en/methods/page/RawContent.md
@@ -25,7 +25,7 @@ This is useful when rendering a page in a plain text [output format].
[Shortcodes] within the content are not rendered. To get the raw content with shortcodes rendered, use the [`RenderShortcodes`] method on a `Page` object.
[shortcodes]: /getting-started/glossary/#shortcode
-[`RenderShortcodes`]: /methods/page/rendershortcodes
+[`RenderShortcodes`]: /methods/page/rendershortcodes/
{{% /note %}}
-[output format]: /templates/output-formats
+[output format]: /templates/output-formats/
diff --git a/docs/content/en/methods/page/RegularPages.md b/docs/content/en/methods/page/RegularPages.md
index b0ca7b1e1..d3327702e 100644
--- a/docs/content/en/methods/page/RegularPages.md
+++ b/docs/content/en/methods/page/RegularPages.md
@@ -72,7 +72,7 @@ In the last example, the collection includes pages in the resources subdirectory
{{% note %}}
When used with the `Site` object, the `RegularPages` method recursively returns all regular pages within the site. See [details].
-[details]: /methods/site/regularpages
+[details]: /methods/site/regularpages/
{{% /note %}}
```go-html-template
diff --git a/docs/content/en/methods/page/Render.md b/docs/content/en/methods/page/Render.md
index bc3f58352..9a70d2bed 100644
--- a/docs/content/en/methods/page/Render.md
+++ b/docs/content/en/methods/page/Render.md
@@ -70,6 +70,6 @@ layouts/_default/li.html
See [content views] for more examples.
-[content views]: /templates/views
-[`partial`]: /functions/partials/include
+[content views]: /templates/views/
+[`partial`]: /functions/partials/include/
[content type]: /getting-started/glossary/#content-type
diff --git a/docs/content/en/methods/page/RenderShortcodes.md b/docs/content/en/methods/page/RenderShortcodes.md
index 4636bf8f5..a4120f69a 100644
--- a/docs/content/en/methods/page/RenderShortcodes.md
+++ b/docs/content/en/methods/page/RenderShortcodes.md
@@ -22,11 +22,12 @@ Use this method in shortcode templates to compose a page from multiple content f
For example:
{{< code file=layouts/shortcodes/include.html >}}
-{{ $p := site.GetPage (.Get 0) }}
-{{ $p.RenderShortcodes }}
+{{ with site.GetPage (.Get 0) }}
+ {{ .RenderShortcodes }}
+{{ end }}
{{< /code >}}
-Then in your markdown:
+Then call the shortcode in your Markdown:
{{< code file=content/about.md lang=md >}}
{{%/* include "/snippets/services.md" */%}}
@@ -34,14 +35,14 @@ Then in your markdown:
{{%/* include "/snippets/leadership.md" */%}}
{{< /code >}}
-Each of the included markdown files can contain calls to other shortcodes.
+Each of the included Markdown files can contain calls to other shortcodes.
## Shortcode notation
In the example above it's important to understand the difference between the two delimiters used when calling a shortcode:
- `{{}}` tells Hugo that the rendered shortcode does not need further processing. For example, the shortcode content is HTML.
-- `{{%/* myshortcode */%}}` tells Hugo that the rendered shortcode needs further processing. For example, the shortcode content is markdown.
+- `{{%/* myshortcode */%}}` tells Hugo that the rendered shortcode needs further processing. For example, the shortcode content is Markdown.
Use the latter for the "include" shortcode described above.
@@ -75,4 +76,4 @@ https://example.org/privacy/
An *emphasized* word.
```
-Note that the shortcode within the content file was rendered, but the surrounding markdown was preserved.
+Note that the shortcode within the content file was rendered, but the surrounding Markdown was preserved.
diff --git a/docs/content/en/methods/page/RenderString.md b/docs/content/en/methods/page/RenderString.md
index 5782cd2b1..1a92c78c6 100644
--- a/docs/content/en/methods/page/RenderString.md
+++ b/docs/content/en/methods/page/RenderString.md
@@ -47,5 +47,5 @@ Render with [Pandoc]:
{{ .RenderString $opts $s }} → H2O
``` -[markup identifier]: /content-management/formats/#list-of-content-formats +[markup identifier]: /content-management/formats/#classification [pandoc]: https://www.pandoc.org/ diff --git a/docs/content/en/methods/page/Resources.md b/docs/content/en/methods/page/Resources.md index 140b50020..54a61a2e4 100644 --- a/docs/content/en/methods/page/Resources.md +++ b/docs/content/en/methods/page/Resources.md @@ -75,11 +75,11 @@ With the `GetMatch` and `Match` methods, Hugo determines a match using a case-in {{% include "functions/_common/glob-patterns.md" %}} -[`resources.ByType`]: /functions/resources/ByType -[`resources.GetMatch`]: /functions/resources/ByType -[`resources.Get`]: /functions/resources/ByType -[`resources.Match`]: /functions/resources/ByType -[`resources`]: /functions/resources +[`resources.ByType`]: /functions/resources/ByType/ +[`resources.GetMatch`]: /functions/resources/ByType/ +[`resources.Get`]: /functions/resources/ByType/ +[`resources.Match`]: /functions/resources/ByType/ +[`resources`]: /functions/resources/ [glob pattern]: https://github.com/gobwas/glob#example [media type]: https://en.wikipedia.org/wiki/Media_type [page bundle]: /getting-started/glossary/#page-bundle diff --git a/docs/content/en/methods/page/Scratch.md b/docs/content/en/methods/page/Scratch.md index f9ce7f7fb..8fef31893 100644 --- a/docs/content/en/methods/page/Scratch.md +++ b/docs/content/en/methods/page/Scratch.md @@ -1,6 +1,6 @@ --- title: Scratch -description: Creates a "scratch pad" on the given page to store and manipulate data. +description: Returns a "scratch pad" on the given page to store and manipulate data. categories: [] keywords: [] action: @@ -9,6 +9,7 @@ action: - functions/collections/NewScratch returnType: maps.Scratch signatures: [PAGE.Scratch] +toc: true aliases: [/extras/scratch/,/doc/scratch/,/functions/scratch] --- @@ -16,8 +17,28 @@ The `Scratch` method on a `Page` object creates a [scratch pad] to store and man To create a locally scoped scratch pad that is not attached to a `Page` object, use the [`newScratch`] function. -[`Store`]: /methods/page/store -[`newScratch`]: functions/collections/newscratch +[`Store`]: /methods/page/store/ +[`newScratch`]: /functions/collections/newscratch/ [scratch pad]: /getting-started/glossary/#scratch-pad {{% include "methods/page/_common/scratch-methods.md" %}} + +## 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. + +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: + +[noop]: /getting-started/glossary/#noop + +```go-html-template +{{ $noop := .Content }} +{{ .Store.Get "mykey" }} +``` + +You can also trigger content rendering with the `FuzzyWordCount`, `Len`, `Plain`, `PlainWords`, `ReadingTime`, `Summary`, `Truncated`, and `WordCount` methods. For example: + +```go-html-template +{{ $noop := .WordCount }} +{{ .Store.Get "mykey" }} +``` diff --git a/docs/content/en/methods/page/Section.md b/docs/content/en/methods/page/Section.md index 30c8a9837..8e027a5a1 100644 --- a/docs/content/en/methods/page/Section.md +++ b/docs/content/en/methods/page/Section.md @@ -50,5 +50,5 @@ This is similar to using the [`Type`] method with the `where` function However, if the `type` field in front matter has been defined on one or more pages, the page collection based on `Type` will be different than the page collection based on `Section`. -[`where`]: /functions/collections/where -[`Type`]: /methods/page/type +[`where`]: /functions/collections/where/ +[`Type`]: /methods/page/type/ diff --git a/docs/content/en/methods/page/Sections.md b/docs/content/en/methods/page/Sections.md index d64440038..4cce1a4fb 100644 --- a/docs/content/en/methods/page/Sections.md +++ b/docs/content/en/methods/page/Sections.md @@ -35,11 +35,11 @@ content/ │ ├── bidding.md │ └── payment.md ├── books/ -│ ├── _index.md <-- front matter: weight = 10 +│ ├── _index.md <-- front matter: weight = 20 │ ├── book-1.md │ └── book-2.md ├── films/ -│ ├── _index.md <-- front matter: weight = 20 +│ ├── _index.md <-- front matter: weight = 10 │ ├── film-1.md │ └── film-2.md └── _index.md diff --git a/docs/content/en/methods/page/Site.md b/docs/content/en/methods/page/Site.md index 34748facd..d83c45e0a 100644 --- a/docs/content/en/methods/page/Site.md +++ b/docs/content/en/methods/page/Site.md @@ -12,7 +12,7 @@ action: See [Site methods]. -[Site methods]: /methods/site +[Site methods]: /methods/site/ ```go-html-template {{ .Site.Title }} diff --git a/docs/content/en/methods/page/Sitemap.md b/docs/content/en/methods/page/Sitemap.md index 08ff3f5d0..d6159267d 100644 --- a/docs/content/en/methods/page/Sitemap.md +++ b/docs/content/en/methods/page/Sitemap.md @@ -14,15 +14,22 @@ Access to the `Sitemap` method on a `Page` object is restricted to [sitemap temp ## Methods -ChangeFreq -: (`string`) How frequently a page is likely to change. Valid values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, and `never`. Default is "" (change frequency omitted from rendered sitemap). +changefreq +: (`string`) How frequently a page is likely to change. Valid values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, and `never`. With the default value of `""` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#changefreqdef). ```go-html-template {{ .Sitemap.ChangeFreq }} ``` -Priority -: (`float`) The priority of a page relative to any other page on the site. Valid values range from 0.0 to 1.0. Default is -1 (priority omitted from rendered sitemap). +disable {{< new-in 0.125.0 >}} +: (`bool`) Whether to disable page inclusion. Default is `false`. Set to `true` in front matter to exclude the page. + +```go-html-template +{{ .Sitemap.Disable }} +``` + +priority +: (`float`) The priority of a page relative to any other page on the site. Valid values range from 0.0 to 1.0. With the default value of `-1` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#priority). ```go-html-template {{ .Sitemap.Priority }} diff --git a/docs/content/en/methods/page/Sites.md b/docs/content/en/methods/page/Sites.md index 1fbdfcdcd..cd240655e 100644 --- a/docs/content/en/methods/page/Sites.md +++ b/docs/content/en/methods/page/Sites.md @@ -52,10 +52,10 @@ Produces a list of links to each home page: ``` -To render a link to home page of the primary (first) language: +To render a link to the home page of the site corresponding to the default content language: ```go-html-template -{{ with .Sites.First }} +{{ with .Sites.Default }} {{ .Title }} {{ end }} ``` diff --git a/docs/content/en/methods/page/Store.md b/docs/content/en/methods/page/Store.md index 8bc16034b..e7090fe79 100644 --- a/docs/content/en/methods/page/Store.md +++ b/docs/content/en/methods/page/Store.md @@ -1,6 +1,6 @@ --- title: Store -description: Creates a persistent "scratch pad" on the given page to store and manipulate data. +description: Returns a persistent "scratch pad" on the given page to store and manipulate data. categories: [] keywords: [] action: @@ -9,6 +9,7 @@ action: - functions/collections/NewScratch returnType: maps.Scratch signatures: [PAGE.Store] +toc: true aliases: [/functions/store] --- @@ -16,8 +17,8 @@ The `Store` method on a `Page` object creates a persistent [scratch pad] to stor 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 +[`Scratch`]: /methods/page/scratch/ +[`newScratch`]: /functions/collections/newscratch/ [scratch pad]: /getting-started/glossary/#scratch-pad ## Methods @@ -102,3 +103,23 @@ Removes the given key. {{ .Store.Set "greeting" "Hello" }} {{ .Store.Delete "greeting" }} ``` + +## 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. + +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: + +[noop]: /getting-started/glossary/#noop + +```go-html-template +{{ $noop := .Content }} +{{ .Store.Get "mykey" }} +``` + +You can also trigger content rendering with the `FuzzyWordCount`, `Len`, `Plain`, `PlainWords`, `ReadingTime`, `Summary`, `Truncated`, and `WordCount` methods. For example: + +```go-html-template +{{ $noop := .WordCount }} +{{ .Store.Get "mykey" }} +``` diff --git a/docs/content/en/methods/page/Summary.md b/docs/content/en/methods/page/Summary.md index 37ce86589..e4542d258 100644 --- a/docs/content/en/methods/page/Summary.md +++ b/docs/content/en/methods/page/Summary.md @@ -11,10 +11,14 @@ action: signatures: [PAGE.Summary] --- + + + + There are three ways to define the [content 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. +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. To list the pages in a section with a summary beneath each link: @@ -26,4 +30,4 @@ To list the pages in a section with a summary beneath each link: {{ end }} ``` -[content summary]: /content-management/summaries +[content summary]: /content-management/summaries/ diff --git a/docs/content/en/methods/page/TableOfContents.md b/docs/content/en/methods/page/TableOfContents.md index 2ab182e8c..38c3ff17b 100644 --- a/docs/content/en/methods/page/TableOfContents.md +++ b/docs/content/en/methods/page/TableOfContents.md @@ -8,9 +8,10 @@ action: - methods/page/Fragments returnType: template.HTML signatures: [PAGE.TableOfContents] +aliases: [/content-management/toc/] --- -The `TableOfContents` method on a `Page` object returns an ordered or unordered list of the markdown [ATX] and [setext] headings within the page content. +The `TableOfContents` method on a `Page` object returns an ordered or unordered list of the Markdown [ATX] and [setext] headings within the page content. [atx]: https://spec.commonmark.org/0.30/#atx-headings [setext]: https://spec.commonmark.org/0.30/#setext-headings diff --git a/docs/content/en/methods/page/Title.md b/docs/content/en/methods/page/Title.md index 52e46ff44..5c2c98d6b 100644 --- a/docs/content/en/methods/page/Title.md +++ b/docs/content/en/methods/page/Title.md @@ -20,19 +20,21 @@ title = 'About us' {{ .Title }} → About us ``` -With section pages not backed by a file, the `Title` method returns the section name, pluralized and converted to title case. - -To disable [pluralization]: +With section, taxonomy, and term pages not backed by a file, the `Title` method returns the section name, capitalized and pluralized. You can disable these transformations by setting [`capitalizeListTitles`] and [`pluralizeListTitles`] in your site configuration. For example: {{< code-toggle file=hugo >}} +capitalizeListTitles = false pluralizeListTitles = false {{< /code-toggle >}} -To change the [title case style], specify one of `ap`, `chicago`, `go`, `firstupper`, or `none`: +You can change the capitalization style in your site configuration to one of `ap`, `chicago`, `go`, `firstupper`, or `none`. For example: {{< code-toggle file=hugo >}} -titleCaseStyle = "ap" +titleCaseStyle = "firstupper" {{< /code-toggle >}} -[pluralization]: /functions/inflect/pluralize -[title case style]: /getting-started/configuration/#configure-title-case + See [details]. + +[`capitalizeListTitles`]: /getting-started/configuration/#capitalizelisttitles +[`pluralizeListTitles`]: /getting-started/configuration/#pluralizelisttitles +[details]: /getting-started/configuration/#configure-title-case diff --git a/docs/content/en/methods/page/Translations.md b/docs/content/en/methods/page/Translations.md index 1ed256630..597a9aeb6 100644 --- a/docs/content/en/methods/page/Translations.md +++ b/docs/content/en/methods/page/Translations.md @@ -1,6 +1,6 @@ --- title: Translations -description: Returns all translation of the given page, excluding the current language. +description: Returns all translations of the given page, excluding the current language. categories: [] keywords: [] action: @@ -63,9 +63,9 @@ And this template: {{ with .Translations }}Pager {{ .PageNumber }} of {{ .TotalPages }}
+| Color | +Relative luminance | +
|---|---|
| {{ .ColorHex }} | +{{ .Luminance | lang.FormatNumber 4 }} | +
This is light text on a dark background.
+{{ debug.Dump .Site.Languages }}
```
With this site configuration:
diff --git a/docs/content/en/methods/site/LastChange.md b/docs/content/en/methods/site/LastChange.md
index aceee691d..2a8c3e491 100644
--- a/docs/content/en/methods/site/LastChange.md
+++ b/docs/content/en/methods/site/LastChange.md
@@ -9,13 +9,19 @@ action:
signatures: [SITE.LastChange]
---
+{{% deprecated-in 0.123.0 %}}
+Use [`.Site.Lastmod`] instead.
+
+[`.Site.Lastmod`]: /methods/site/lastmod/
+{{% /deprecated-in %}}
+
The `LastChange` method on a `Site` object returns a [`time.Time`] value. Use this with time [functions] and [methods]. For example:
```go-html-template
-{{ .Site.LastChange | time.Format ":date_long" }} → October 16, 2023
+{{ .Site.LastChange | time.Format ":date_long" }} → January 31, 2024
```
[`time.Time`]: https://pkg.go.dev/time#Time
-[functions]: /functions/time
-[methods]: /methods/time
+[functions]: /functions/time/
+[methods]: /methods/time/
diff --git a/docs/content/en/methods/site/Lastmod.md b/docs/content/en/methods/site/Lastmod.md
new file mode 100644
index 000000000..081481956
--- /dev/null
+++ b/docs/content/en/methods/site/Lastmod.md
@@ -0,0 +1,23 @@
+---
+title: Lastmod
+description: Returns the last modification date of site content.
+categories: []
+keywords: []
+action:
+ related: []
+ returnType: time.Time
+ signatures: [SITE.Lastmod]
+---
+
+{{< new-in 0.123.0 >}}
+
+The `Lastmod` method on a `Site` object returns a [`time.Time`] value. Use this with time [functions] and [methods]. For example:
+
+```go-html-template
+{{ .Site.Lastmod | time.Format ":date_long" }} → January 31, 2024
+
+```
+
+[`time.Time`]: https://pkg.go.dev/time#Time
+[functions]: /functions/time/
+[methods]: /methods/time/
diff --git a/docs/content/en/methods/site/Menus.md b/docs/content/en/methods/site/Menus.md
index c204fe97b..98ce4e879 100644
--- a/docs/content/en/methods/site/Menus.md
+++ b/docs/content/en/methods/site/Menus.md
@@ -88,7 +88,7 @@ You will typically render a menu using a partial template. As the active menu en
The example above is simplistic. Please see the [menu templates] section for more information.
-[menu templates]: /templates/menu-templates
+[menu templates]: /templates/menu-templates/
-[`partial`]: /functions/partials/include
-[`partialCached`]: /functions/partials/includecached
+[`partial`]: /functions/partials/include/
+[`partialCached`]: /functions/partials/includecached/
diff --git a/docs/content/en/methods/site/Pages.md b/docs/content/en/methods/site/Pages.md
index 583e98c11..ac6e13c4a 100644
--- a/docs/content/en/methods/site/Pages.md
+++ b/docs/content/en/methods/site/Pages.md
@@ -16,7 +16,7 @@ This method returns all page [kinds] in the current language. That includes the
In most cases you should use the [`RegularPages`] method instead.
-[`RegularPages`]: methods/site/regularpages
+[`RegularPages`]: /methods/site/regularpages/
[kinds]: /getting-started/glossary/#page-kind
```go-html-template
diff --git a/docs/content/en/methods/site/Params.md b/docs/content/en/methods/site/Params.md
index 518d93bf3..95e016b81 100644
--- a/docs/content/en/methods/site/Params.md
+++ b/docs/content/en/methods/site/Params.md
@@ -33,7 +33,7 @@ Access the custom parameters by [chaining] the [identifiers]:
{{ .Site.Params.author.name }} → John Smith
{{ $layout := .Site.Params.layouts.rfc_1123 }}
-{{ .Site.LastChange.Format $layout }} → Tue, 17 Oct 2023 13:21:02 PDT
+{{ .Site.Lastmod.Format $layout }} → Tue, 17 Oct 2023 13:21:02 PDT
```
In the template example above, each of the keys is a valid identifier. For example, none of the keys contains a hyphen. To access a key that is not a valid identifier, use the [`index`] function:
@@ -42,6 +42,6 @@ In the template example above, each of the keys is a valid identifier. For examp
{{ index .Site.Params "copyright-year" }} → 2023
```
-[`index`]: /functions/collections/indexfunction
+[`index`]: /functions/collections/indexfunction/
[chaining]: /getting-started/glossary/#chain
[identifiers]: /getting-started/glossary/#identifier
diff --git a/docs/content/en/methods/site/Sites.md b/docs/content/en/methods/site/Sites.md
index f7bafd3ed..ac287d3b4 100644
--- a/docs/content/en/methods/site/Sites.md
+++ b/docs/content/en/methods/site/Sites.md
@@ -1,6 +1,6 @@
---
title: Sites
-description: Returns a collection of all Site objects, one for each language, ordered by language weight.
+description: Returns a collection of all Site objects, one for each language, ordered by default content language then by language weight.
categories: []
keywords: []
action:
@@ -49,10 +49,10 @@ Produces a list of links to each home page:
```
-To render a link to home page of the primary (first) language:
+To render a link to the home page of the site corresponding to the default content language:
```go-html-template
-{{ with .Site.Sites.First }}
+{{ with .Site.Sites.Default }}
{{ .Title }}
{{ end }}
```
diff --git a/docs/content/en/methods/site/Taxonomies.md b/docs/content/en/methods/site/Taxonomies.md
index 72bfc75d5..219fe188b 100644
--- a/docs/content/en/methods/site/Taxonomies.md
+++ b/docs/content/en/methods/site/Taxonomies.md
@@ -95,5 +95,5 @@ Hugo's taxonomy system is powerful, allowing you to classify content and create
Please see the [taxonomies] section for a complete explanation and examples.
-[taxonomies]: content-management/taxonomies/
+[taxonomies]: /content-management/taxonomies/
{{% /note %}}
diff --git a/docs/content/en/methods/taxonomy/Alphabetical.md b/docs/content/en/methods/taxonomy/Alphabetical.md
index 7845dbf3d..ea90cfdf9 100644
--- a/docs/content/en/methods/taxonomy/Alphabetical.md
+++ b/docs/content/en/methods/taxonomy/Alphabetical.md
@@ -34,7 +34,7 @@ To reverse the sort order:
To inspect the data structure:
```go-html-template
-{{ jsonify (dict "indent" " ") $taxonomyObject.Alphabetical }}
+{{ debug.Dump $taxonomyObject.Alphabetical }}
```
{{% include "methods/taxonomy/_common/ordered-taxonomy-element-methods.md" %}}
diff --git a/docs/content/en/methods/taxonomy/ByCount.md b/docs/content/en/methods/taxonomy/ByCount.md
index 40f58420a..68143ccff 100644
--- a/docs/content/en/methods/taxonomy/ByCount.md
+++ b/docs/content/en/methods/taxonomy/ByCount.md
@@ -34,7 +34,7 @@ To reverse the sort order:
To inspect the data structure:
```go-html-template
-{{ jsonify (dict "indent" " ") $taxonomyObject.ByCount }}
+{{ debug.Dump $taxonomyObject.ByCount }}
```
{{% include "methods/taxonomy/_common/ordered-taxonomy-element-methods.md" %}}
diff --git a/docs/content/en/methods/taxonomy/Get.md b/docs/content/en/methods/taxonomy/Get.md
index 3bac86f08..79d25b704 100644
--- a/docs/content/en/methods/taxonomy/Get.md
+++ b/docs/content/en/methods/taxonomy/Get.md
@@ -43,7 +43,7 @@ You could also use the [`index`] function, but the syntax is more verbose:
To inspect the data structure:
```go-html-template
-{{ jsonify (dict "indent" " ") $weightedPages }}
+{{ debug.Dump $weightedPages }}
```
## Example
@@ -66,7 +66,7 @@ Hugo renders:
```
[chaining]: /getting-started/glossary/#chain
-[`index`]: /functions/collections/indexfunction
+[`index`]: /functions/collections/indexfunction/
[identifier]: /getting-started/glossary/#identifier
[term]: /getting-started/glossary/#term
[weighted pages]: /getting-started/glossary/#weighted-page
diff --git a/docs/content/en/methods/taxonomy/Page.md b/docs/content/en/methods/taxonomy/Page.md
new file mode 100644
index 000000000..e148ac5c7
--- /dev/null
+++ b/docs/content/en/methods/taxonomy/Page.md
@@ -0,0 +1,26 @@
+---
+title: Page
+description: Returns the taxonomy page or nil if the taxonomy has no terms.
+categories: []
+keywords: []
+action:
+ related: []
+ returnType: page.Page
+ signatures: [TAXONOMY.Page]
+---
+
+{{< new-in 0.125.0 >}}
+
+This `TAXONOMY` method returns nil if the taxonomy has no terms, so you must code defensively:
+
+```go-html-template
+{{ with .Site.Taxonomies.tags.Page }}
+ {{ .LinkTitle }}
+{{ end }}
+```
+
+This is rendered to:
+
+```html
+Tags
+```
diff --git a/docs/content/en/methods/taxonomy/_common/_index.md b/docs/content/en/methods/taxonomy/_common/_index.md
index 47d5812fb..4328d4d14 100644
--- a/docs/content/en/methods/taxonomy/_common/_index.md
+++ b/docs/content/en/methods/taxonomy/_common/_index.md
@@ -7,7 +7,7 @@ cascade:
---
diff --git a/docs/content/en/methods/taxonomy/_common/get-a-taxonomy-object.md b/docs/content/en/methods/taxonomy/_common/get-a-taxonomy-object.md
index 4c4fc42c9..6bf86cd85 100644
--- a/docs/content/en/methods/taxonomy/_common/get-a-taxonomy-object.md
+++ b/docs/content/en/methods/taxonomy/_common/get-a-taxonomy-object.md
@@ -41,7 +41,7 @@ To capture the "genres" taxonomy object when rendering its page with a taxonomy
To inspect the data structure:
```go-html-template
-{{ jsonify (dict "indent" " ") $taxonomyObject }}
+{{ debug.Dump $taxonomyObject }}
```
Although the [`Alphabetical`] and [`ByCount`] methods provide a better data structure for ranging through the taxonomy, you can render the weighted pages by term directly from the `Taxonomy` object:
@@ -60,9 +60,9 @@ Although the [`Alphabetical`] and [`ByCount`] methods provide a better data stru
In the example above, the first anchor element is a link to the term page.
-[`Alphabetical`]: /methods/taxonomy/alphabetical
-[`ByCount`]: /methods/taxonomy/bycount
+[`Alphabetical`]: /methods/taxonomy/alphabetical/
+[`ByCount`]: /methods/taxonomy/bycount/
-[`data`]: /methods/page/data
+[`data`]: /methods/page/data/
[`terms`]: /methods/page/data/#in-a-taxonomy-template
-[`taxonomies`]: /methods/site/taxonomies
+[`taxonomies`]: /methods/site/taxonomies/
diff --git a/docs/content/en/methods/taxonomy/_common/ordered-taxonomy-element-methods.md b/docs/content/en/methods/taxonomy/_common/ordered-taxonomy-element-methods.md
index 9c94729ba..7201ad318 100644
--- a/docs/content/en/methods/taxonomy/_common/ordered-taxonomy-element-methods.md
+++ b/docs/content/en/methods/taxonomy/_common/ordered-taxonomy-element-methods.md
@@ -21,5 +21,5 @@ Term
WeightedPages
: (`page.WeightedPages`) Returns a slice of weighted pages to which the term is assigned, sorted by [taxonomic weight]. The `Pages` method above is more flexible, allowing you to sort and group.
-[methods]: /methods/pages
+[methods]: /methods/pages/
[taxonomic weight]: /getting-started/glossary/#taxonomic-weight
diff --git a/docs/content/en/methods/time/Format.md b/docs/content/en/methods/time/Format.md
index fc3e2635c..d526b7b64 100644
--- a/docs/content/en/methods/time/Format.md
+++ b/docs/content/en/methods/time/Format.md
@@ -27,7 +27,7 @@ aliases: [/methods/time/format]
To [localize] the return value, use the [`time.Format`] function instead.
[localize]: /getting-started/glossary/#localization
-[`time.Format`]: /functions/time/format
+[`time.Format`]: /functions/time/format/
{{% /note %}}
Use the `Format` method with any `time.Time` value, including the four predefined front matter dates:
@@ -44,7 +44,7 @@ Use the `Format` method with any `time.Time` value, including the four predefine
{{% note %}}
Use the [`time.Format`] function to format string representations of dates, and to format raw TOML dates that exclude time and time zone offset.
-[`time.Format`]: /functions/time/format
+[`time.Format`]: /functions/time/format/
{{% /note %}}
## Layout string
diff --git a/docs/content/en/methods/time/Round.md b/docs/content/en/methods/time/Round.md
new file mode 100644
index 000000000..988c56ba9
--- /dev/null
+++ b/docs/content/en/methods/time/Round.md
@@ -0,0 +1,26 @@
+---
+title: Round
+description: Returns the result of rounding TIME to the nearest multiple of DURATION since January 1, 0001, 00:00:00 UTC.
+categories: []
+keywords: []
+action:
+ related:
+ - functions/time/AsTime
+ - functions/time/ParseDuration
+ - methods/time/Truncate
+ returnType: time.Time
+ signatures: [TIME.Round DURATION]
+---
+
+The rounding behavior for halfway values is to round up.
+
+The `Round` method operates on TIME as an absolute duration since the [zero time]; it does not operate on the presentation form of the time. If DURATION is a multiple of one hour, `Round` may return a time with a non-zero minute, depending on the time zone.
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $d := time.ParseDuration "1h"}}
+
+{{ ($t.Round $d).Format "2006-01-02T15:04:05-00:00" }} → 2023-01-28T00:00:00-00:00
+```
+
+[zero time]: /getting-started/glossary/#zero-time
diff --git a/docs/content/en/methods/time/Truncate.md b/docs/content/en/methods/time/Truncate.md
new file mode 100644
index 000000000..da6e0b26b
--- /dev/null
+++ b/docs/content/en/methods/time/Truncate.md
@@ -0,0 +1,24 @@
+---
+title: Truncate
+description: Returns the result of rounding TIME down to a multiple of DURATION since January 1, 0001, 00:00:00 UTC.
+categories: []
+keywords: []
+action:
+ related:
+ - functions/time/AsTime
+ - functions/time/ParseDuration
+ - methods/time/Round
+ returnType: time.Time
+ signatures: [TIME.Truncate DURATION]
+---
+
+The `Truncate` method operates on TIME as an absolute duration since the [zero time]; it does not operate on the presentation form of the time. If DURATION is a multiple of one hour, `Truncate` may return a time with a non-zero minute, depending on the time zone.
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $d := time.ParseDuration "1h"}}
+
+{{ ($t.Truncate $d).Format "2006-01-02T15:04:05-00:00" }} → 2023-01-27T23:00:00-00:00
+```
+
+[zero time]: /getting-started/glossary/#zero-time
diff --git a/docs/content/en/methods/time/YearDay.md b/docs/content/en/methods/time/YearDay.md
index 40d7d6aab..f380cdffe 100644
--- a/docs/content/en/methods/time/YearDay.md
+++ b/docs/content/en/methods/time/YearDay.md
@@ -1,6 +1,6 @@
---
title: YearDay
-description: Returns the day of the year of the given time.Time value, in the range [1, 365] for non-leap years, and [1,366] in leap years.
+description: Returns the day of the year of the given time.Time value, in the range [1, 365] for non-leap years, and [1, 366] in leap years.
categories: []
keywords: []
action:
diff --git a/docs/content/en/news/_index.md b/docs/content/en/news/_index.md
index e37c33a3c..a1959bd1d 100644
--- a/docs/content/en/news/_index.md
+++ b/docs/content/en/news/_index.md
@@ -1,4 +1,7 @@
---
-title: Hugo News
+title: News
+outputs:
+ - html
+ - rss
aliases: [/release-notes/]
---
diff --git a/docs/content/en/quick-reference/_index.md b/docs/content/en/quick-reference/_index.md
index 492cfa09b..b5f434e2d 100644
--- a/docs/content/en/quick-reference/_index.md
+++ b/docs/content/en/quick-reference/_index.md
@@ -1,12 +1,12 @@
---
title: Quick reference guides
-linkTitle: Overview
+linkTitle: In this section
description: Quick reference guides to Hugo's features, functions, and methods.
categories: []
keywords: []
menu:
docs:
- identifier: quick-reference-overview
+ identifier: quick-reference-in-this-section
parent: quick-reference
weight: 10
weight: 10
diff --git a/docs/content/en/quick-reference/emojis.md b/docs/content/en/quick-reference/emojis.md
index e6b1ed415..8ae01098b 100644
--- a/docs/content/en/quick-reference/emojis.md
+++ b/docs/content/en/quick-reference/emojis.md
@@ -1,6 +1,6 @@
---
title: Emojis
-description: Include emoji shortcodes in your markdown or templates.
+description: Include emoji shortcodes in your Markdown or templates.
categories: [quick reference]
keywords: [emoji]
menu:
@@ -11,13 +11,13 @@ weight: 20
toc: true
---
-Configure Hugo to enable emoji processing in markdown:
+Configure Hugo to enable emoji processing in Markdown:
{{< code-toggle file=hugo >}}
enableEmoji = true
{{< /code-toggle >}}
-With emoji processing enabled, this markdown:
+With emoji processing enabled, this Markdown:
```md
Hello! :wave:
@@ -37,8 +37,8 @@ To process an emoji shortcode from within a template, use the [`emojify`] functi
{{ "Hello! :wave:" | .RenderString }}
```
-[`emojify`]: /functions/transform/emojify
-[`RenderString`]: /methods/page/renderstring
+[`emojify`]: /functions/transform/emojify/
+[`RenderString`]: /methods/page/renderstring/
## Introduction
diff --git a/docs/content/en/quick-reference/page-collections.md b/docs/content/en/quick-reference/page-collections.md
index 795eb494d..eca65a93e 100644
--- a/docs/content/en/quick-reference/page-collections.md
+++ b/docs/content/en/quick-reference/page-collections.md
@@ -31,7 +31,7 @@ Use these `Site` methods when rendering lists on any page.
Use the [`where`] function to filter page collections.
-[`where`]: /functions/collections/where
+[`where`]: /functions/collections/where/
## Sort
diff --git a/docs/content/en/variables/_common/_index.md b/docs/content/en/render-hooks/_common/_index.md
similarity index 79%
rename from docs/content/en/variables/_common/_index.md
rename to docs/content/en/render-hooks/_common/_index.md
index 47d5812fb..4328d4d14 100644
--- a/docs/content/en/variables/_common/_index.md
+++ b/docs/content/en/render-hooks/_common/_index.md
@@ -7,7 +7,7 @@ cascade:
---
diff --git a/docs/content/en/render-hooks/_common/pageinner.md b/docs/content/en/render-hooks/_common/pageinner.md
new file mode 100644
index 000000000..de1316cba
--- /dev/null
+++ b/docs/content/en/render-hooks/_common/pageinner.md
@@ -0,0 +1,42 @@
+---
+# Do not remove front matter.
+---
+
+## PageInner details
+
+{{< new-in 0.125.0 >}}
+
+The primary use case for `PageInner` is to resolve links and [page resources] relative to an included `Page`. For example, create an "include" shortcode to compose a page from multiple content files, while preserving a global context for footnotes and the table of contents:
+
+{{< code file=layouts/shortcodes/include.html >}}
+{{ with site.GetPage (.Get 0) }}
+ {{ .RenderShortcodes }}
+{{ end }}
+{{< /code >}}
+
+Then call the shortcode in your Markdown:
+
+{{< code file=content/posts/p1.md >}}
+{{%/* include "/posts/p2" */%}}
+{{< /code >}}
+
+Any render hook triggered while rendering `/posts/p2` will get:
+
+- `/posts/p1` when calling `Page`
+- `/posts/p2` when calling `PageInner`
+
+`PageInner` falls back to the value of `Page` if not relevant, and always returns a value.
+
+{{% note %}}
+The `PageInner` method is only relevant for shortcodes that invoke the [`RenderShortcodes`] method, and you must call the shortcode using the `{{%/*..*/%}}` notation.
+
+[`RenderShortcodes`]: /methods/page/rendershortcodes/
+{{% /note %}}
+
+As a practical example, Hugo's embedded link and image render hooks use the `PageInner` method to resolve markdown link and image destinations. See the source code for each:
+
+- [Embedded link render hook]({{% eturl render-link %}})
+- [Embedded image render hook]({{% eturl render-image %}})
+
+[`RenderShortcodes`]: /methods/page/rendershortcodes/
+[page resources]: /getting-started/glossary/#page-resource
diff --git a/docs/content/en/render-hooks/_index.md b/docs/content/en/render-hooks/_index.md
new file mode 100644
index 000000000..8cf72c4e8
--- /dev/null
+++ b/docs/content/en/render-hooks/_index.md
@@ -0,0 +1,17 @@
+---
+title: Render hooks
+linkTitle: In this section
+description: Create render hooks to override the rendering of Markdown to HTML.
+categories: []
+keywords: []
+menu:
+ docs:
+ identifier: render-hooks-in-this-section
+ parent: render-hooks
+ weight: 10
+weight: 10
+showSectionMenu: false
+aliases: [/templates/render-hooks/]
+---
+
+Create render hooks to override the rendering of Markdown to HTML.
diff --git a/docs/content/en/render-hooks/code-blocks.md b/docs/content/en/render-hooks/code-blocks.md
new file mode 100755
index 000000000..0c11c7864
--- /dev/null
+++ b/docs/content/en/render-hooks/code-blocks.md
@@ -0,0 +1,152 @@
+---
+title: Code block render hooks
+linkTitle: Code blocks
+description: Create a code block render hook to override the rendering of Markdown code blocks to HTML.
+categories: [render hooks]
+keywords: []
+menu:
+ docs:
+ parent: render-hooks
+ weight: 30
+weight: 30
+toc: true
+---
+
+## Markdown
+
+This Markdown example contains a fenced code block:
+
+{{< code file=content/example.md lang=text >}}
+```bash {class="my-class" id="my-codeblock" lineNos=inline tabWidth=2}
+declare a=1
+echo "$a"
+exit
+```
+{{< /code >}}
+
+A fenced code block consists of:
+
+- A leading [code fence]
+- An optional [info string]
+- A code sample
+- A trailing code fence
+
+[code fence]: https://spec.commonmark.org/0.31.2/#code-fence
+[info string]: https://spec.commonmark.org/0.31.2/#info-string
+
+In the previous example, the info string contains:
+
+- The language of the code sample (the first word)
+- An optional space-delimited or comma-delimited list of attributes (everything within braces)
+
+The attributes in the info string can be generic attributes or highlighting options.
+
+In the example above, the _generic attributes_ are `class` and `id`. In the absence of special handling within a code block render hook, Hugo adds each generic attribute to the HTML element surrounding the rendered code block. Consistent with its content security model, Hugo removes HTML event attributes such as `onclick` and `onmouseover`. Generic attributes are typically global HTML attributes, but you may include custom attributes as well.
+
+In the example above, the _highlighting options_ are `lineNos` and `tabWidth`. Hugo uses the [Chroma] syntax highlighter to render the code sample. You can control the appearance of the rendered code by specifying one or more [highlighting options].
+
+[Chroma]: https://github.com/alecthomas/chroma/
+[highlighting options]: /functions/transform/highlight/#options
+
+{{% note %}}
+Although `style` is a global HTML attribute, when used in an info string it is a highlighting option.
+{{% /note %}}
+
+## Context
+
+Code block render hook templates receive the following [context]:
+
+[context]: /getting-started/glossary/#context
+
+###### Attributes
+
+(`map`) The generic attributes from the info string.
+
+###### Inner
+
+(`string`) The content between the leading and trailing code fences, excluding the info string.
+
+###### Options
+
+(`map`) The highlighting options from the info string.
+
+###### Ordinal
+
+(`int`) The zero-based ordinal of the code block on the page.
+
+###### Page
+
+(`page`) A reference to the current page.
+
+###### PageInner
+
+{{< new-in 0.125.0 >}}
+
+(`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
+
+[`RenderShortcodes`]: /methods/page/rendershortcodes
+
+###### Position
+
+(`text.Position`) The position of the code block within the page content.
+
+###### Type
+
+(`string`) The first word of the info string, typically the code language.
+
+## Examples
+
+In its default configuration, Hugo renders fenced code blocks by passing the code sample through the Chroma syntax highlighter and wrapping the result. To create a render hook that does the same thing:
+
+[CommonMark specification]: https://spec.commonmark.org/current/
+
+{{< code file=layouts/_default/_markup/render-codeblock.html copy=true >}}
+{{ $result := transform.HighlightCodeBlock . }}
+{{ $result.Wrapped }}
+{{< /code >}}
+
+Although you can use one template with conditional logic to control the behavior on a per-language basis, you can also create language-specific templates.
+
+```text
+layouts/
+└── _default/
+ └── _markup/
+ ├── render-codeblock-mermaid.html
+ ├── render-codeblock-python.html
+ └── render-codeblock.html
+```
+
+For example, to create a code block render hook to render [Mermaid] diagrams:
+
+[Mermaid]: https://mermaid.js.org/
+
+{{< code file=layouts/_default/_markup/render-codeblock-mermaid.html copy=true >}}
+
+ {{- .Inner | safeHTML }}
+
+{{ .Page.Store.Set "hasMermaid" true }}
+{{< /code >}}
+
+Then include this snippet at the bottom of the your base template:
+
+{{< code file=layouts/_default/baseof.html copy=true >}}
+{{ if .Store.Get "hasMermaid" }}
+
+{{ end }}
+{{< /code >}}
+
+See the [diagrams] page for details.
+
+[diagrams]: /content-management/diagrams/#mermaid-diagrams
+
+## Embedded
+
+Hugo includes an [embedded code block render hook] to render [GoAT diagrams].
+
+[embedded code block render hook]: {{% eturl render-codeblock-goat %}}
+[GoAT diagrams]: /content-management/diagrams/#goat-diagrams-ascii
+
+{{% include "/render-hooks/_common/pageinner.md" %}}
diff --git a/docs/content/en/render-hooks/headings.md b/docs/content/en/render-hooks/headings.md
new file mode 100755
index 000000000..c48bb11e1
--- /dev/null
+++ b/docs/content/en/render-hooks/headings.md
@@ -0,0 +1,79 @@
+---
+title: Heading render hooks
+linkTitle: Headings
+description: Create a heading render hook to override the rendering of Markdown headings to HTML.
+categories: [render hooks]
+keywords: []
+menu:
+ docs:
+ parent: render-hooks
+ weight: 40
+weight: 40
+toc: true
+---
+
+## Context
+
+Heading render hook templates receive the following [context]:
+
+[context]: /getting-started/glossary/#context
+
+###### Anchor
+
+(`string`) The `id` attribute of the heading element.
+
+###### Attributes
+
+(`map`) The Markdown attributes, available if you configure your site as follows:
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.parser.attribute]
+title = true
+{{< /code-toggle >}}
+
+###### Level
+
+(`int`) The heading level, 1 through 6.
+
+###### Page
+
+(`page`) A reference to the current page.
+
+###### PageInner
+
+{{< new-in 0.125.0 >}}
+
+(`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
+
+[`RenderShortcodes`]: /methods/page/rendershortcodes
+
+###### PlainText
+
+(`string`) The heading text as plain text.
+
+###### Text
+
+(`string`) The heading text.
+
+## Examples
+
+In its default configuration, Hugo renders Markdown headings according to the [CommonMark specification] with the addition of automatic `id` attributes. To create a render hook that does the same thing:
+
+[CommonMark specification]: https://spec.commonmark.org/current/
+
+{{< code file=layouts/_default/_markup/render-heading.html copy=true >}}
+
The page you requested cannot be found.
++ + Return to the home page + +
{{ end }} {{< /code >}} -## Automatic loading +For multilingual sites, add the language key to the file name: -Your 404.html file can be set to load automatically when a visitor enters a mistaken URL path, dependent upon the web serving environment you are using. For example: +```text +layouts/ +├── 404.de.html +├── 404.en.html +└── 404.fr.html +``` -* [GitHub Pages](/hosting-and-deployment/hosting-on-github/), [GitLab Pages](/hosting-and-deployment/hosting-on-gitlab/) and [Cloudflare Pages](/hosting-and-deployment/hosting-on-cloudflare-pages/). The 404 page is automatic. -* Apache. You can specify `ErrorDocument 404 /404.html` in an `.htaccess` file in the root of your site. -* Nginx. You might specify `error_page 404 /404.html;` in your `nginx.conf` file. [Details here](https://nginx.org/en/docs/http/ngx_http_core_module.html#error_page). -* Amazon AWS S3. When setting a bucket up for static web serving, you can specify the error file from within the S3 GUI. -* Amazon CloudFront. You can specify the page in the Error Pages section in the CloudFront Console. [Details here](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/custom-error-pages.html) -* Caddy Server. Use the `handle_errors` directive to specify error pages for one or more status codes. [Details here](https://caddyserver.com/docs/caddyfile/directives/handle_errors) -* Netlify. Add `/* /404.html 404` to `content/_redirects`. [Details Here](https://www.netlify.com/docs/redirects/#custom-404) -* Azure Static Web App. set `responseOverrides.404.rewrite` and `responseOverrides.404.statusCode` in configfile `staticwebapp.config.json`. [Details here](https://docs.microsoft.com/en-us/azure/static-web-apps/configuration#response-overrides) -* Azure Storage as Static Web Site Hosting. You can specify the `Error document path` in the Static website configuration page of the Azure portal. [Details here](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website). -* DigitalOcean App Platform. You can specify `error_document` in your app specification file or use control panel to set up error document. [Details here](https://docs.digitalocean.com/products/app-platform/how-to/manage-static-sites/#configure-a-static-site). -* [Firebase Hosting](https://firebase.google.com/docs/hosting/full-config#404): `/404.html` automatically gets used as the 404 page. +Your production server redirects the browser to the 404 page when a page is not found. Capabilities and configuration vary by host. -[pagevars]: /variables/page/ +Host|Capabilities and configuration +:--|:-- +Amazon CloudFront|See [details](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/GeneratingCustomErrorResponses.html). +Amazon S3|See [details](https://docs.aws.amazon.com/AmazonS3/latest/userguide/CustomErrorDocSupport.html). +Apache|See [details](https://httpd.apache.org/docs/2.4/custom-error.html). +Azure Static Web Apps|See [details](https://learn.microsoft.com/en-us/azure/static-web-apps/configuration#response-overrides). +Azure Storage|See [details](https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website#setting-up-a-static-website). +Caddy|See [deatils](https://caddyserver.com/docs/caddyfile/directives/handle_errors). +Cloudflare Pages|See [details](https://developers.cloudflare.com/pages/configuration/serving-pages/#not-found-behavior). +DigitalOcean App Platform|See [details](https://docs.digitalocean.com/products/app-platform/how-to/manage-static-sites/#configure-a-static-site). +Firebase|See [details](https://firebase.google.com/docs/hosting/full-config#404). +GitHub Pages|Redirection to is automatic and not configurable. +GitLab Pages|See [details](https://docs.gitlab.com/ee/user/project/pages/introduction.html#custom-error-codes-pages). +NGINX|See [details](https://nginx.org/en/docs/http/ngx_http_core_module.html#error_page). +Netlify|See [details](https://docs.netlify.com/routing/redirects/redirect-options/). diff --git a/docs/content/en/templates/_index.md b/docs/content/en/templates/_index.md index b2197d162..23b2a3eaf 100644 --- a/docs/content/en/templates/_index.md +++ b/docs/content/en/templates/_index.md @@ -1,12 +1,12 @@ --- title: Templates -linkTitle: Overview +linkTitle: In this section description: Go templating, template types and lookup order, shortcodes, and data. categories: [] keywords: [] menu: docs: - identifier: templates-overview + identifier: templates-in-this-section parent: templates weight: 10 weight: 10 diff --git a/docs/content/en/templates/base.md b/docs/content/en/templates/base.md index 63bf2f9b2..6262e74b8 100644 --- a/docs/content/en/templates/base.md +++ b/docs/content/en/templates/base.md @@ -91,7 +91,7 @@ The following shows how you can override both the `"main"` and `"title"` block a {{ end }} {{< /code >}} -[hugolists]: /templates/lists +[hugolists]: /templates/lists/ [lookup]: /templates/lookup-order/ [rendering the section]: /templates/section-templates/ [singletemplate]: /templates/single-page-templates/ diff --git a/docs/content/en/templates/data-templates.md b/docs/content/en/templates/data-templates.md deleted file mode 100644 index 435bd70b2..000000000 --- a/docs/content/en/templates/data-templates.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -title: Data templates -description: In addition to Hugo's built-in variables, you can specify your own custom data in templates or shortcodes that pull from both local and dynamic sources. -categories: [templates] -keywords: [data,dynamic,csv,json,toml,yaml,xml] -menu: - docs: - parent: templates - weight: 150 -weight: 150 -toc: true -aliases: [/extras/datafiles/,/extras/datadrivencontent/,/doc/datafiles/] ---- - -Hugo supports loading data from YAML, JSON, XML, and TOML files located in the `data` directory at the root of your Hugo project. - -{{< youtube FyPgSuwIMWQ >}} - -## The data directory - -The `data` directory should store additional data for Hugo to use when generating your site. - -Data files are not for generating standalone pages. They should supplement content files by: - -- Extending the content when the front matter fields grow out of control, or -- Showing a larger dataset in a template (see the example below). - -In both cases, it's a good idea to outsource the data in their (own) files. - -These files must be YAML, JSON, XML, or TOML files (using the `.yml`, `.yaml`, `.json`, `.xml`, or `.toml` extension). The data will be accessible as a `map` in the `.Site.Data` variable. - -To access the data using the `site.Data.filename` notation, the file name must begin with an underscore or a Unicode letter, followed by zero or more underscores, Unicode letters, or Unicode digits. For example: - -- `123.json` - Invalid -- `x123.json` - Valid -- `_123.json` - Valid - -To access the data using the [`index`](/functions/collections/indexfunction) function, the file name is irrelevant. For example: - -Data file|Template code -:--|:-- -`123.json`|`{{ index .Site.Data "123" }}` -`x123.json`|`{{ index .Site.Data "x123" }}` -`_123.json`|`{{ index .Site.Data "_123" }}` -`x-123.json`|`{{ index .Site.Data "x-123" }}` - -## Data files in themes - -Data Files can also be used in themes. - -However, note that the theme data files are merged with the project directory taking precedence. That is, Given two files with the same name and relative path, the data in the file in the root project `data` directory will override the data from the file in the `themes/{{ index .Site.Data.user0123 "Short Description" | markdownify }}
The product of {{ $v1 }} and {{ $v2 }} is {{ mul $v1 $v2 }}.
``` -Parameters for functions are separated using spaces. The general syntax is: +While HTML templates are the most common, you can create templates for any [output format] including CSV, JSON, RSS, and plain text. -```go-html-template -{{ FUNCTION ARG1 ARG2 .. }} +[output format]: /templates/output-formats/ + +## Context + +The most important concept to understand before creating a template is _context_, the data passed into each template. The data may be a simple value, or more commonly [objects] and associated [methods]. + +[objects]: /getting-started/glossary/#object +[methods]: /getting-started/glossary/#method + +For example, a template for a single page receives a `Page` object, and the `Page` object provides methods to return values or perform actions. + +### Current context + +Within a template, the dot (`.`) represents the current context. + +{{< code file=layouts/_default/single.html >}} +{{ . }}
+{{ end }} + +{{ with "baz" }} +{{ . }}
+{{ end }} +{{< /code >}} + +In the example above, the context changes as we `range` through the [slice] of values. In the first iteration the context is "foo", and in the second iteration the context is "bar". Inside of the `with` block the context is "baz". Hugo renders the above to: + +[slice]: /getting-started/glossary/#slice + +```html +foo
+bar
+baz
``` -The following example calls the `add` function with inputs of `1` and `2`: +### Template context -```go-html-template -{{ add 1 2 }} +Within a `range` or `with` block you can access the context passed into the template by prepending a dollar sign (`$`) to the dot: + +{{< code file=layouts/_default/single.html >}} +{{ with "foo" }} +{{ $.Title }} - {{ . }}
+{{ end }} +{{< /code >}} + +Hugo renders this to: + +```html +My Page Title - foo
``` -#### Methods and fields are accessed via dot notation +{{% note %}} +Make sure that you thoroughly understand the concept of _context_ before you continue reading. The most common templating errors made by new users relate to context. +{{% /note %}} -Accessing the Page Parameter `bar` defined in a piece of content's [front matter]. +## Actions -```go-html-template -{{ .Params.bar }} +In the examples above the paired opening and closing braces represent the beginning and end of a template action, a data evaluation or control structure within a template. + +A template action may contain literal values ([boolean], [string], [integer], and [float]), variables, functions, and methods. + +[boolean]: /getting-started/glossary/#boolean +[string]: /getting-started/glossary/#string +[integer]: /getting-started/glossary/#integer +[float]: /getting-started/glossary/#float + +{{< code file=layouts/_default/single.html >}} +{{ $convertToLower := true }} +{{ if $convertToLower }} +