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

Merge commit 'e509cac533600cf4fa8382c9cdab78ddd82db688'

Browse Source
This commit is contained in:
Bjørn Erik Pedersen
2023-10-20 09:43:56 +02:00
parent fd38171810 e509cac533
commit e2dd4cd05f
298 changed files with 4568 additions and 1991 deletions
Download Patch File Download Diff File Expand all files Collapse all files

72
docs/content/en/functions/urls/AbsLangURL.md Normal file
View File

@@ -0,0 +1,72 @@
---
title: urls.AbsLangURL
linkTitle: absLangURL
description: Returns an absolute URL with a language prefix, if any.
categories: [functions]
keywords: []
menu:
docs:
parent: functions
function:
aliases: [absLangURL]
returnType: template.HTML
signatures: [urls.AbsLangURL INPUT]
relatedFunctions:
- urls.AbsLangURL
- urls.AbsURL
- urls.RelLangURL
- urls.RelURL
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
- 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.
### 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`.
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
```
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
```
### 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`.
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
```
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 %}}
The last three examples are not desirable in most situations. As a best practice, never include a leading slash when using this function.
{{% /note %}}

71
docs/content/en/functions/urls/AbsURL.md Normal file
View File

@@ -0,0 +1,71 @@
---
title: urls.AbsURL
linkTitle: absURL
description: Returns an absolute URL.
categories: [functions]
keywords: []
menu:
docs:
parent: functions
function:
aliases: [absURL]
returnType: template.html
signatures: [urls.AbsURL INPUT]
relatedFunctions:
- urls.AbsLangURL
- urls.AbsURL
- urls.RelLangURL
- urls.RelURL
aliases: [/functions/absurl]
---
With multilingual configurations, use the [`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`.
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
```
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
```
#### 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`.
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
```
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
```
{{% 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/

31
docs/content/en/functions/urls/Anchorize.md Normal file
View File

@@ -0,0 +1,31 @@
---
title: urls.Anchorize
linkTitle: anchorize
description: Takes a string and sanitizes it the same way as the [`defaultMarkdownHandler`](/getting-started/configuration-markup#default-configuration) does for markdown headers.
categories: [functions]
keywords: []
menu:
docs:
parent: functions
function:
aliases: [anchorize]
returnType: string
signatures: [urls.Anchorize INPUT]
relatedFunctions:
- urls.Anchorize
- urls.URLize
aliases: [/functions/anchorize]
---
If [Goldmark](/getting-started/configuration-markup#goldmark) is set as `defaultMarkdownHandler`, the sanitizing logic adheres to the setting [`markup.goldmark.parser.autoHeadingIDType`](/getting-started/configuration-markup#goldmark).
Since the `defaultMarkdownHandler` and this template function use the same sanitizing logic, you can use the latter to determine the ID of a header for linking with anchor tags.
```go-html-template
{{ anchorize "This is a header" }} → "this-is-a-header"
{{ anchorize "This is also a header" }} → "this-is-also----a-header"
{{ anchorize "main.go" }} → "maingo"
{{ anchorize "Article 123" }} → "article-123"
{{ anchorize "<- Let's try this, shall we?" }} → "--lets-try-this-shall-we"
{{ anchorize "Hello, 世界" }} → "hello-世界"
```

32
docs/content/en/functions/urls/JoinPath.md Normal file
View File

@@ -0,0 +1,32 @@
---
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: [functions]
keywords: []
menu:
docs:
parent: functions
function:
aliases: []
returnType: string
signatures: [urls.JoinPath ELEMENT...]
relatedFunctions:
- path.Join
- urls.JoinPath
aliases: [/functions/urls.joinpath]
---
```go-html-template
{{ urls.JoinPath }} → ""
{{ urls.JoinPath "" }} → "/"
{{ urls.JoinPath "a" }} → "a"
{{ urls.JoinPath "a" "b" }} → "a/b"
{{ urls.JoinPath "/a" "b" }} → "/a/b"
{{ urls.JoinPath "https://example.org" "b" }} → "https://example.org/b"
{{ urls.JoinPath (slice "a" "b") }} → "a/b"
```
Unlike the [`path.Join`] function, `urls.JoinPath` retains consecutive leading slashes.
[`path.Join`]: /functions/path/join

37
docs/content/en/functions/urls/Parse.md Normal file
View File

@@ -0,0 +1,37 @@
---
title: urls.Parse
description: Parses a URL into a URL structure.
categories: [functions]
keywords: []
menu:
docs:
parent: functions
function:
aliases: []
returnType: URL
signatures: [urls.Parse URL]
relatedFunctions: []
aliases: [/functions/urls.parse]
---
The `urls.Parse` function parses a URL into a [URL structure](https://godoc.org/net/url#URL). The URL may be relative (a path, without a host) or absolute (starting with a [scheme]). Hugo throws an error when parsing an invalid URL.
[scheme]: https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml#uri-schemes-1
```go-html-template
{{ $url := "https://example.org:123/foo?a=6&b=7#bar" }}
{{ $u := urls.Parse $url }}
{{ $u.IsAbs }} → true
{{ $u.Scheme }} → https
{{ $u.Host }} → example.org:123
{{ $u.Hostname }} → example.org
{{ $u.RequestURI }} → /foo?a=6&b=7
{{ $u.Path }} → /foo
{{ $u.Query }} → map[a:[6] b:[7]]
{{ $u.Query.a }} → [6]
{{ $u.Query.Get "a" }} → 6
{{ $u.Query.Has "b" }} → true
{{ $u.Fragment }} → bar
```

49
docs/content/en/functions/urls/Ref.md Normal file
View File

@@ -0,0 +1,49 @@
---
title: urls.Ref
linkTitle: ref
description: Returns the absolute permalink to a page.
categories: [functions]
keywords: []
menu:
docs:
parent: functions
function:
aliases: [ref]
returnType: template.HTML
signatures: [urls.Ref . PAGE]
relatedFunctions:
- urls.Ref
- urls.RelRef
aliases: [/functions/ref]
---
This function takes two arguments:
- The context of the page from which to resolve relative paths, typically the current page (`.`)
- The 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.
```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" }}
```
To return the absolute permalink to another language version of a page:
```go-html-template
{{ ref . (dict "path" "about.md" "lang" "fr") }}
```
To return the absolute permalink to another Output Format of a page:
```go-html-template
{{ ref . (dict "path" "about.md" "outputFormat" "rss") }}
```
Hugo emits an error or warning if the page cannot be uniquely resolved. The error behavior is configurable; see [Ref and RelRef Configuration](/content-management/cross-references/#ref-and-relref-configuration).
This function is used by Hugo's built-in [`ref`](/content-management/shortcodes/#ref-and-relref) shortcode. For a detailed explanation of how to leverage this shortcode for content management, see [Links and Cross References](/content-management/cross-references/).

72
docs/content/en/functions/urls/RelLangURL.md Normal file
View File

@@ -0,0 +1,72 @@
---
title: urls.RelLangURL
linkTitle: relLangURL
description: Returns a relative URL with a language prefix, if any.
categories: [functions]
keywords: []
menu:
docs:
parent: functions
function:
aliases: [relLangURL]
returnType: template.HTML
signatures: [urls.RelLangURL INPUT]
relatedFunctions:
- urls.AbsLangURL
- urls.AbsURL
- urls.RelLangURL
- urls.RelURL
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 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.
### 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`.
With `baseURL = https://example.org/`
```go-html-template
{{ relLangURL "" }} → /en/
{{ relLangURL "articles" }} → /en/articles
{{ relLangURL "style.css" }} → /en/style.css
```
With `baseURL = https://example.org/docs/`
```go-html-template
{{ relLangURL "" }} → /docs/en/
{{ relLangURL "articles" }} → /docs/en/articles
{{ relLangURL "style.css" }} → /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`.
With `baseURL = https://example.org/`
```go-html-template
{{ 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
```
{{% 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 %}}

56
docs/content/en/functions/urls/RelRef.md Normal file
View File

@@ -0,0 +1,56 @@
---
title: urls.RelRef
linkTitle: relref
description: Returns the relative permalink to a page.
categories: [functions]
keywords: []
menu:
docs:
parent: functions
function:
aliases: [relref]
returnType: template.HTML
signatures: [urls.RelRef . PAGE]
relatedFunctions:
- urls.Ref
- urls.RelRef
aliases: [/functions/relref]
---
This function takes two arguments:
- The context of the page from which to resolve relative paths, typically the current page (`.`)
- The 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.
```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 permalink returned is relative to the protocol+host portion of the baseURL specified in the site configuration. For example:
Code|baseURL|Permalink
:--|:--|:--
`{{ relref . "/about" }}`|`http://example.org/`|`/about/`
`{{ relref . "/about" }}`|`http://example.org/x/`|`/x/about/`
To return the relative permalink to another language version of a page:
```go-html-template
{{ relref . (dict "path" "about.md" "lang" "fr") }}
```
To return the relative permalink to another Output Format of a page:
```go-html-template
{{ relref . (dict "path" "about.md" "outputFormat" "rss") }}
```
Hugo emits an error or warning if the page cannot be uniquely resolved. The error behavior is configurable; see [Ref and RelRef Configuration](/content-management/cross-references/#ref-and-relref-configuration).
This function is used by Hugo's built-in [`relref`](/content-management/shortcodes/#ref-and-relref) shortcode. For a detailed explanation of how to leverage this shortcode for content management, see [Links and Cross References](/content-management/cross-references/).

71
docs/content/en/functions/urls/RelURL.md Normal file
View File

@@ -0,0 +1,71 @@
---
title: urls.RelURL
linkTitle: relURL
description: Returns a relative URL.
categories: [functions]
keywords: []
menu:
docs:
parent: functions
function:
aliases: [relURL]
returnType: template.HTML
signatures: [urls.RelURL INPUT]
relatedFunctions:
- urls.AbsLangURL
- urls.AbsURL
- urls.RelLangURL
- urls.RelURL
aliases: [/functions/relurl]
---
With multilingual configurations, use the [`relLangURL`] 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`.
With `baseURL = https://example.org/`
```go-html-template
{{ relURL "" }} → /
{{ relURL "articles" }} → /articles
{{ relURL "style.css" }} → /style.css
```
With `baseURL = https://example.org/docs/`
```go-html-template
{{ relURL "" }} → /docs/
{{ relURL "articles" }} → /docs/articles
{{ relURL "style.css" }} → /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`.
With `baseURL = https://example.org/`
```go-html-template
{{ 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
```
{{% 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/

69
docs/content/en/functions/urls/URLize.md Normal file
View File

@@ -0,0 +1,69 @@
---
title: urls.URLize
linkTitle: urlize
description: Takes a string, sanitizes it for usage in URLs, and converts spaces to hyphens.
categories: [functions]
keywords: []
menu:
docs:
parent: functions
function:
aliases: [urlize]
returnType: string
signatures: [urls.URLize INPUT]
relatedFunctions:
- urls.Anchorize
- urls.URLize
aliases: [/functions/urlize]
---
The following examples pull from a content file with the following front matter:
{{< code-toggle file="content/blog/greatest-city.md" fm=true copy=false >}}
title = "The World's Greatest City"
location = "Chicago IL"
tags = ["pizza","beer","hot dogs"]
{{< /code-toggle >}}
The following might be used as a partial within a [single page template][singletemplate]:
{{< code file="layouts/partials/content-header.html" >}}
<header>
<h1>{{ .Title }}</h1>
{{ with .Params.location }}
<div><a href="/locations/{{ . | urlize }}">{{ . }}</a></div>
{{ end }}
<!-- Creates a list of tags for the content and links to each of their pages -->
{{ with .Params.tags }}
<ul>
{{ range .}}
<li>
<a href="/tags/{{ . | urlize }}">{{ . }}</a>
</li>
{{ end }}
</ul>
{{ end }}
</header>
{{< /code >}}
The preceding partial would then output to the rendered page as follows:
```html
<header>
<h1>The World&#39;s Greatest City</h1>
<div><a href="/locations/chicago-il">Chicago IL</a></div>
<ul>
<li>
<a href="/tags/pizza">pizza</a>
</li>
<li>
<a href="/tags/beer">beer</a>
</li>
<li>
<a href="/tags/hot-dogs">hot dogs</a>
</li>
</ul>
</header>
```
[singletemplate]: /templates/single-page-templates/