Merge commit '5be51ac3db225d5df501ed1fa1499c41d97dbf65'

This commit is contained in:
Bjørn Erik Pedersen
2025-04-10 13:04:51 +02:00
987 changed files with 12379 additions and 14083 deletions

View File

@@ -3,50 +3,56 @@ title: urls.AbsLangURL
description: Returns an absolute URL with a language prefix, if any.
categories: []
keywords: []
action:
aliases: [absLangURL]
related:
- functions/urls/AbsURL
- functions/urls/RelLangURL
- functions/urls/RelURL
returnType: string
signatures: [urls.AbsLangURL INPUT]
params:
functions_and_methods:
aliases: [absLangURL]
returnType: string
signatures: [urls.AbsLangURL INPUT]
aliases: [/functions/abslangurl]
---
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
- Whether the input begins with a slash (`/`)
- The `baseURL` in your site configuration
- The language prefix, if any
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.
This is the site configuration for the examples that follow:
### Input does not begin with a slash
{{< code-toggle file=hugo >}}
defaultContentLanguage = 'en'
defaultContentLanguageInSubdir = true
[languages.en]
weight = 1
[languages.es]
weight = 2
{{< /code-toggle >}}
## Input does not begin with a slash
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/`
When rendering the `en` site 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/`
When rendering the `en` site 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
## Input begins with a slash
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/`
When rendering the `en` site with `baseURL = https://example.org/`
```go-html-template
{{ absLangURL "/" }} → https://example.org/en/
@@ -54,10 +60,13 @@ With `baseURL = https://example.org/`
{{ absLangURL "/style.css" }} → https://example.org/en/style.css
```
With `baseURL = https://example.org/docs/`
When rendering the `en` site 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
```
> [!note]
> As illustrated by the previous example, using a leading slash is rarely desirable and can lead to unexpected outcomes. In nearly all cases, omit the leading slash.

View File

@@ -3,23 +3,20 @@ title: urls.AbsURL
description: Returns an absolute URL.
categories: []
keywords: []
action:
aliases: [absURL]
related:
- functions/urls/AbsLangURL
- functions/urls/RelLangURL
- functions/urls/RelURL
returnType: string
signatures: [urls.AbsURL INPUT]
params:
functions_and_methods:
aliases: [absURL]
returnType: string
signatures: [urls.AbsURL INPUT]
aliases: [/functions/absurl]
---
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
- Whether the input begins with a slash (`/`)
- The `baseURL` in your site configuration
### Input does not begin with a slash
## Input does not begin with a slash
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.
@@ -39,7 +36,7 @@ With `baseURL = https://example.org/docs/`
{{ absURL "style.css" }} → https://example.org/docs/style.css
```
#### Input begins with a slash
## Input begins with a slash
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.
@@ -59,4 +56,7 @@ With `baseURL = https://example.org/docs/`
{{ absURL "/style.css" }} → https://example.org/style.css
```
> [!note]
> As illustrated by the previous example, using a leading slash is rarely desirable and can lead to unexpected outcomes. In nearly all cases, omit the leading slash.
[`urls.AbsLangURL`]: /functions/urls/abslangurl/

View File

@@ -3,16 +3,15 @@ title: urls.Anchorize
description: Returns the given string, sanitized for usage in an HTML id attribute.
categories: []
keywords: []
action:
aliases: [anchorize]
related:
- functions/urls/URLize
returnType: string
signatures: [urls.Anchorize INPUT]
params:
functions_and_methods:
aliases: [anchorize]
returnType: string
signatures: [urls.Anchorize INPUT]
aliases: [/functions/anchorize]
---
{{% include "/functions/urls/_common/anchorize-vs-urlize.md" %}}
{{% include "/_common/functions/urls/anchorize-vs-urlize.md" %}}
## Sanitizing logic
@@ -31,7 +30,7 @@ github
: Compatible with GitHub. This is the default.
github-ascii
: Similar to the `github` setting, but removes non-ASCII characters.
: Similar to the `github` setting, but removes non-ASCII characters.
blackfriday
: Provided for backwards compatibility with Hugo v0.59.1 and earlier. This option will be removed in a future release.

View File

@@ -3,12 +3,11 @@ title: urls.JoinPath
description: Joins the provided elements into a URL string and cleans the result of any ./ or ../ elements. If the argument list is empty, JoinPath returns an empty string.
categories: []
keywords: []
action:
aliases: []
related:
- functions/path/Join
returnType: string
signatures: [urls.JoinPath ELEMENT...]
params:
functions_and_methods:
aliases: []
returnType: string
signatures: [urls.JoinPath ELEMENT...]
aliases: [/functions/urls.joinpath]
---

View File

@@ -3,11 +3,11 @@ title: urls.Parse
description: Parses a URL into a URL structure.
categories: []
keywords: []
action:
aliases: []
related: []
returnType: url.URL
signatures: [urls.Parse URL]
params:
functions_and_methods:
aliases: []
returnType: url.URL
signatures: [urls.Parse URL]
aliases: [/functions/urls.parse]
---
@@ -26,6 +26,7 @@ The `urls.Parse` function parses a URL into a [URL structure](https://godoc.org/
{{ $u.Hostname }} → example.org
{{ $u.RequestURI }} → /foo?a=6&b=7
{{ $u.Path }} → /foo
{{ $u.RawQuery }} → a=6&b=7
{{ $u.Query }} → map[a:[6] b:[7]]
{{ $u.Query.a }} → [6]
{{ $u.Query.Get "a" }} → 6

View File

@@ -1,63 +1,46 @@
---
title: urls.Ref
description: Returns the absolute permalink to a page at the given path.
description: Returns the absolute URL of the page with the given path, language, and output format.
categories: []
keywords: []
action:
aliases: [ref]
related:
- functions/urls/RelRef
- methods/page/Ref
- methods/page/RelRef
returnType: string
signatures:
- urls.Ref PAGE PATH
- urls.Ref PAGE OPTIONS
params:
functions_and_methods:
aliases: [ref]
returnType: string
signatures:
- urls.Ref PAGE PATH
- urls.Ref PAGE OPTIONS
aliases: [/functions/ref]
---
The first argument is the context of the page from which to resolve relative paths, typically the current page.
## Usage
The second argument is a path to a page, with or without a file extension, with or without an anchor. A path without a leading `/` is first resolved relative to the given context, then to the remainder of the site. Alternatively, provide an [options map](#options) instead of a path.
The `ref` function takes two arguments:
```go-html-template
{{ ref . "about" }}
{{ ref . "about#anchor" }}
{{ ref . "about.md" }}
{{ ref . "about.md#anchor" }}
{{ ref . "#anchor" }}
{{ ref . "/blog/my-post" }}
{{ ref . "/blog/my-post.md" }}
```
1. The context for resolving relative paths (typically the current page).
1. Either the target page's path or an options map (see below).
## Options
Instead of specifying a path, you can also provide an options map:
{{% include "_common/ref-and-relref-options.md" %}}
path
: (`string`) The path to the page, relative to the `content` directory. Required.
## Examples
lang
: (`string`) The language (site) to search for the page. Default is the current language. Optional.
outputFormat
: (`string`) The output format to search for the page. Default is the current output format. Optional.
To return the absolute permalink to another language version of a page:
The following examples show the rendered output for a page on the English version of the site:
```go-html-template
{{ ref . (dict "path" "about.md" "lang" "fr") }}
{{ ref . "/books/book-1" }} → https://example.org/en/books/book-1/
{{ $opts := dict "path" "/books/book-1" }}
{{ ref . $opts }} → https://example.org/en/books/book-1/
{{ $opts := dict "path" "/books/book-1" "lang" "de" }}
{{ ref . $opts }} → https://example.org/de/books/book-1/
{{ $opts := dict "path" "/books/book-1" "lang" "de" "outputFormat" "json" }}
{{ ref . $opts }} → https://example.org/de/books/book-1/index.json
```
To return the absolute permalink to another Output Format of a page:
## Error handling
```go-html-template
{{ ref . (dict "path" "about.md" "outputFormat" "rss") }}
```
By default, Hugo will throw an error and fail the build if it cannot resolve the path. You can change this to a warning in your site configuration, and specify a URL to return when the path cannot be resolved.
{{< code-toggle file=hugo >}}
refLinksErrorLevel = 'warning'
refLinksNotFoundURL = '/some/other/url'
{{< /code-toggle >}}
{{% include "_common/ref-and-relref-error-handling.md" %}}

View File

@@ -3,52 +3,66 @@ title: urls.RelLangURL
description: Returns a relative URL with a language prefix, if any.
categories: []
keywords: []
action:
aliases: [relLangURL]
related:
- functions/urls/AbsLangURL
- functions/urls/AbsURL
- functions/urls/RelURL
returnType: string
signatures: [urls.RelLangURL INPUT]
params:
functions_and_methods:
aliases: [relLangURL]
returnType: string
signatures: [urls.RelLangURL INPUT]
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
- Whether the input begins with a slash (`/`)
- The `baseURL` in your site configuration
- The language prefix, if any
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.
This is the site configuration for the examples that follow:
### Input does not begin with a slash
{{< code-toggle file=hugo >}}
defaultContentLanguage = 'en'
defaultContentLanguageInSubdir = true
[languages.en]
weight = 1
[languages.es]
weight = 2
{{< /code-toggle >}}
## Input does not begin with a slash
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/`
When rendering the `en` site with `baseURL = https://example.org/`
```go-html-template
{{ relLangURL "" }} → /en/
{{ relLangURL "articles" }} → /en/articles
{{ relLangURL "style.css" }} → /en/style.css
{{ relLangURL "https://example.org/foo" }} → /en/foo
{{ relLangURL "" }} → /en/
{{ relLangURL "articles" }} → /en/articles
{{ relLangURL "style.css" }} → /en/style.css
{{ relLangURL "https://example.org" }} → https://example.org
{{ relLangURL "https://example.org/" }} → /en
{{ relLangURL "https://www.example.org" }} → https://www.example.org
{{ relLangURL "https://www.example.org/" }} → https://www.example.org/
```
With `baseURL = https://example.org/docs/`
When rendering the `en` site 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 "https://example.org/docs/foo" }} → /docs/en/foo
{{ relLangURL "" }} → /docs/en/
{{ relLangURL "articles" }} → /docs/en/articles
{{ relLangURL "style.css" }} → /docs/en/style.css
{{ relLangURL "https://example.org" }} → https://example.org
{{ relLangURL "https://example.org/" }} → https://example.org/
{{ relLangURL "https://example.org/docs" }} → https://example.org/docs
{{ relLangURL "https://example.org/docs/" }} → /docs/en
{{ relLangURL "https://www.example.org" }} → https://www.example.org
{{ relLangURL "https://www.example.org/" }} → https://www.example.org/
```
#### Input begins with a slash
## Input begins with a slash
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/`
When rendering the `en` site with `baseURL = https://example.org/`
```go-html-template
{{ relLangURL "/" }} → /en/
@@ -56,10 +70,13 @@ With `baseURL = https://example.org/`
{{ relLangURL "/style.css" }} → /en/style.css
```
With `baseURL = https://example.org/docs/`
When rendering the `en` site with `baseURL = https://example.org/docs/`
```go-html-template
{{ relLangURL "/" }} → /en/
{{ relLangURL "/articles" }} → /en/articles
{{ relLangURL "/style.css" }} → /en/style.css
```
> [!note]
> As illustrated by the previous example, using a leading slash is rarely desirable and can lead to unexpected outcomes. In nearly all cases, omit the leading slash.

View File

@@ -1,70 +1,46 @@
---
title: urls.RelRef
description: Returns the relative permalink to a page at the given path.
description: Returns the relative URL of the page with the given path, language, and output format.
categories: []
keywords: []
action:
aliases: [relref]
related:
- functions/urls/Ref
- methods/page/Ref
- methods/page/RelRef
returnType: string
signatures:
- urls.RelRef PAGE PATH
- urls.RelRef PAGE OPTIONS
params:
functions_and_methods:
aliases: [relref]
returnType: string
signatures:
- urls.RelRef PAGE PATH
- urls.RelRef PAGE OPTIONS
aliases: [/functions/relref]
---
The first argument is the context of the page from which to resolve relative paths, typically the current page.
## Usage
The second argument is a path to a page, with or without a file extension, with or without an anchor. A path without a leading `/` is first resolved relative to the given context, then to the remainder of the site. Alternatively, provide an [options map](#options) instead of a path.
.
```go-html-template
{{ relref . "about" }}
{{ relref . "about#anchor" }}
{{ relref . "about.md" }}
{{ relref . "about.md#anchor" }}
{{ relref . "#anchor" }}
{{ relref . "/blog/my-post" }}
{{ relref . "/blog/my-post.md" }}
```
The `relref` function takes two arguments:
The permalink returned is relative to the protocol+host portion of the baseURL specified in the site configuration. For example:
Code|baseURL|Permalink
:--|:--|:--
`{{ relref . "/about" }}`|`https://example.org/`|`/about/`
`{{ relref . "/about" }}`|`https://example.org/x/`|`/x/about/`
1. The context for resolving relative paths (typically the current page).
1. Either the target page's path or an options map (see below).
## Options
Instead of specifying a path, you can also provide an options map:
{{% include "_common/ref-and-relref-options.md" %}}
path
: (`string`) The path to the page, relative to the `content` directory. Required.
## Examples
lang
: (`string`) The language (site) to search for the page. Default is the current language. Optional.
outputFormat
: (`string`) The output format to search for the page. Default is the current output format. Optional.
To return the relative permalink to another language version of a page:
The following examples show the rendered output for a page on the English version of the site:
```go-html-template
{{ relref . (dict "path" "about.md" "lang" "fr") }}
{{ relref . "/books/book-1" }} → /en/books/book-1/
{{ $opts := dict "path" "/books/book-1" }}
{{ relref . $opts }} → /en/books/book-1/
{{ $opts := dict "path" "/books/book-1" "lang" "de" }}
{{ relref . $opts }} → /de/books/book-1/
{{ $opts := dict "path" "/books/book-1" "lang" "de" "outputFormat" "json" }}
{{ relref . $opts }} → /de/books/book-1/index.json
```
To return the relative permalink to another Output Format of a page:
## Error handling
```go-html-template
{{ relref . (dict "path" "about.md" "outputFormat" "rss") }}
```
By default, Hugo will throw an error and fail the build if it cannot resolve the path. You can change this to a warning in your site configuration, and specify a URL to return when the path cannot be resolved.
{{< code-toggle file=hugo >}}
refLinksErrorLevel = 'warning'
refLinksNotFoundURL = '/some/other/url'
{{< /code-toggle >}}
{{% include "_common/ref-and-relref-error-handling.md" %}}

View File

@@ -3,45 +3,50 @@ title: urls.RelURL
description: Returns a relative URL.
categories: []
keywords: []
action:
aliases: [relURL]
related:
- functions/urls/AbsLangURL
- functions/urls/AbsURL
- functions/urls/RelLangURL
returnType: string
signatures: [urls.RelURL INPUT]
params:
functions_and_methods:
aliases: [relURL]
returnType: string
signatures: [urls.RelURL INPUT]
aliases: [/functions/relurl]
---
With multilingual configurations, use the [`urls.RelLangURL`] function instead. The URL returned by this function depends on:
- Whether the input begins with a slash
- Whether the input begins with a slash (`/`)
- The `baseURL` in your site configuration
### Input does not begin with a slash
## Input does not begin with a slash
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 "https://example.org/foo" }} → /foo
{{ relURL "" }} → /
{{ relURL "articles" }} → /articles
{{ relURL "style.css" }} → /style.css
{{ relURL "https://example.org" }} → https://example.org
{{ relURL "https://example.org/" }} → /
{{ relURL "https://www.example.org" }} → https://www.example.org
{{ relURL "https://www.example.org/" }} → https://www.example.org/
```
With `baseURL = https://example.org/docs/`
```go-html-template
{{ relURL "" }} → /docs/
{{ relURL "articles" }} → /docs/articles
{{ relURL "style.css" }} → /docs/style.css
{{ relURL "https://example.org/docs/foo" }} → /docs/foo
{{ relURL "" }} → /docs/
{{ relURL "articles" }} → /docs/articles
{{ relURL "style.css" }} → /docs/style.css
{{ relURL "https://example.org" }} → https://example.org
{{ relURL "https://example.org/" }} → https://example.org/
{{ relURL "https://example.org/docs" }} → https://example.org/docs
{{ relURL "https://example.org/docs/" }} → /docs
{{ relURL "https://www.example.org" }} → https://www.example.org
{{ relURL "https://www.example.org/" }} → https://www.example.org/
```
#### Input begins with a slash
## Input begins with a slash
If the input begins with a slash, the resulting URL will be relative to the protocol+host of the `baseURL` in your site configuration.
@@ -61,4 +66,7 @@ With `baseURL = https://example.org/docs/`
{{ relURL "/style.css" }} → /style.css
```
> [!note]
> As illustrated by the previous example, using a leading slash is rarely desirable and can lead to unexpected outcomes. In nearly all cases, omit the leading slash.
[`urls.RelLangURL`]: /functions/urls/rellangurl/

View File

@@ -3,16 +3,15 @@ title: urls.URLize
description: Returns the given string, sanitized for usage in a URL.
categories: []
keywords: []
action:
aliases: [urlize]
related:
- functions/urls/Anchorize
returnType: string
signatures: [urls.URLize INPUT]
params:
functions_and_methods:
aliases: [urlize]
returnType: string
signatures: [urls.URLize INPUT]
aliases: [/functions/urlize]
---
{{% include "/functions/urls/_common/anchorize-vs-urlize.md" %}}
{{% include "/_common/functions/urls/anchorize-vs-urlize.md" %}}
## Example

View File

@@ -1,13 +0,0 @@
---
cascade:
_build:
list: never
publishResources: false
render: never
---
<!--
Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
Include the rendered content using the "include" shortcode.
-->

View File

@@ -1,35 +0,0 @@
---
_comment: Do not remove front matter.
---
The [`anchorize`] and [`urlize`] functions are similar:
[`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
For example:
```go-html-template
{{ $s := "A B C" }}
{{ $s | anchorize }} → a-b-c
{{ $s | urlize }} → a-b-c
{{ $s := "a b c" }}
{{ $s | anchorize }} → a-b---c
{{ $s | urlize }} → a-b-c
{{ $s := "< a, b, & c >" }}
{{ $s | anchorize }} → -a-b--c-
{{ $s | urlize }} → a-b-c
{{ $s := "main.go" }}
{{ $s | anchorize }} → maingo
{{ $s | urlize }} → main.go
{{ $s := "Hugö" }}
{{ $s | anchorize }} → hugö
{{ $s | urlize }} → hug%C3%B6
```

View File

@@ -1,12 +1,7 @@
---
title: URL functions
linkTitle: urls
description: Template functions to work with URLs.
description: Use these functions to work with URLs.
categories: []
keywords: []
menu:
docs:
parent: functions
---
Use these functions to work with URLs.