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

Merge commit '35dec7c96f7ee3eb17dd444f7067f0c776fb56ae'

Browse Source
This commit is contained in:
Bjørn Erik Pedersen
2023-12-04 15:24:01 +01:00
parent 9f978d387f 35dec7c96f
commit d19ed4d4e6
810 changed files with 24147 additions and 7766 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
docs/content/en/functions/urls/AbsLangURL.md
View File

@@ -1,21 +1,16 @@
---
title: urls.AbsLangURL
linkTitle: absLangURL
description: Returns an absolute URL with a language prefix, if any.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [absLangURL]
returnType: template.HTML
related:
- functions/urls/AbsURL
- functions/urls/RelLangURL
- functions/urls/RelURL
returnType: string
signatures: [urls.AbsLangURL INPUT]
relatedFunctions:
- urls.AbsLangURL
- urls.AbsURL
- urls.RelLangURL
- urls.RelURL
aliases: [/functions/abslangurl]
---

21
docs/content/en/functions/urls/AbsURL.md
View File

@@ -1,25 +1,20 @@
---
title: urls.AbsURL
linkTitle: absURL
description: Returns an absolute URL.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [absURL]
returnType: template.html
related:
- functions/urls/AbsLangURL
- functions/urls/RelLangURL
- functions/urls/RelURL
returnType: string
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:
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

46
docs/content/en/functions/urls/Anchorize.md
View File

@@ -1,31 +1,37 @@
---
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]
description: Returns the given string, sanitized for usage in an HTML id attribute.
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [anchorize]
related:
- functions/urls/URLize
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).
{{% include "/functions/urls/_common/anchorize-vs-urlize.md" %}}
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.
## Sanitizing logic
```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-世界"
```
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.
Set `autoHeadingIDType` to one of:
github
: Compatible with GitHub. This is the default, and strongly recommended.
github-ascii
: 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.

30
docs/content/en/functions/urls/JoinPath.md
View File

@@ -1,30 +1,28 @@
---
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]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: []
related:
- functions/path/Join
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"
{{< new-in 0.112.0 >}}
{{ urls.JoinPath (slice "a" "b") }} → "a/b"
```go-html-template
{{ urls.JoinPath }} → "" (empty string)
{{ 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.

12
docs/content/en/functions/urls/Parse.md
View File

@@ -1,16 +1,13 @@
---
title: urls.Parse
description: Parses a URL into a URL structure.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: []
returnType: URL
related: []
returnType: url.URL
signatures: [urls.Parse URL]
relatedFunctions: []
aliases: [/functions/urls.parse]
---
@@ -18,7 +15,6 @@ The `urls.Parse` function parses a URL into a [URL structure](https://godoc.org/
[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 }}

48
docs/content/en/functions/urls/Ref.md
View File

@@ -1,26 +1,24 @@
---
title: urls.Ref
linkTitle: ref
description: Returns the absolute permalink to a page.
categories: [functions]
description: Returns the absolute permalink to a page at the given path.
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [ref]
returnType: template.HTML
signatures: [urls.Ref . PAGE]
relatedFunctions:
- urls.Ref
- urls.RelRef
related:
- functions/urls/RelRef
- methods/page/Ref
- methods/page/RelRef
returnType: string
signatures:
- urls.Ref PAGE PATH
- urls.Ref PAGE OPTIONS
aliases: [/functions/ref]
---
This function takes two arguments:
The first argument is the context of the page from which to resolve relative paths, typically the current page.
- 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.
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
{{ ref . "about" }}
@@ -32,6 +30,19 @@ This function takes two arguments:
{{ ref . "/blog/my-post.md" }}
```
## Options
Instead of specifying a path, you can also provide an options map:
path
: (`string`) The path to the page, relative to the content directory. Required.
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:
```go-html-template
@@ -44,6 +55,9 @@ To return the absolute permalink to another Output Format of a page:
{{ 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).
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.
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/).
{{< code-toggle file=hugo >}}
refLinksErrorLevel = 'warning'
refLinksNotFoundURL = '/some/other/url'
{{< /code-toggle >}}

23
docs/content/en/functions/urls/RelLangURL.md
View File

@@ -1,21 +1,16 @@
---
title: urls.RelLangURL
linkTitle: relLangURL
description: Returns a relative URL with a language prefix, if any.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [relLangURL]
returnType: template.HTML
related:
- functions/urls/AbsLangURL
- functions/urls/AbsURL
- functions/urls/RelURL
returnType: string
signatures: [urls.RelLangURL INPUT]
relatedFunctions:
- urls.AbsLangURL
- urls.AbsURL
- urls.RelLangURL
- urls.RelURL
aliases: [/functions/rellangurl]
---
@@ -37,7 +32,7 @@ With `baseURL = https://example.org/`
{{ relLangURL "" }} → /en/
{{ relLangURL "articles" }} → /en/articles
{{ relLangURL "style.css" }} → /en/style.css
```
```
With `baseURL = https://example.org/docs/`
@@ -57,7 +52,7 @@ With `baseURL = https://example.org/`
{{ relLangURL "/" }} → /en/
{{ relLangURL "/articles" }} → /en/articles
{{ relLangURL "/style.css" }} → /en/style.css
```
```
With `baseURL = https://example.org/docs/`

54
docs/content/en/functions/urls/RelRef.md
View File

@@ -1,27 +1,25 @@
---
title: urls.RelRef
linkTitle: relref
description: Returns the relative permalink to a page.
categories: [functions]
description: Returns the relative permalink to a page at the given path.
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [relref]
returnType: template.HTML
signatures: [urls.RelRef . PAGE]
relatedFunctions:
- urls.Ref
- urls.RelRef
related:
- functions/urls/Ref
- methods/page/Ref
- methods/page/RelRef
returnType: string
signatures:
- urls.RelRef PAGE PATH
- urls.RelRef PAGE OPTIONS
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.
The first argument is the context of the page from which to resolve relative paths, typically the current page.
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" }}
@@ -36,8 +34,21 @@ The permalink returned is relative to the protocol+host portion of the baseURL s
Code|baseURL|Permalink
:--|:--|:--
`{{ relref . "/about" }}`|`http://example.org/`|`/about/`
`{{ relref . "/about" }}`|`http://example.org/x/`|`/x/about/`
`{{ relref . "/about" }}`|`https://example.org/`|`/about/`
`{{ relref . "/about" }}`|`https://example.org/x/`|`/x/about/`
## Options
Instead of specifying a path, you can also provide an options map:
path
: (`string`) The path to the page, relative to the content directory. Required.
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:
@@ -51,6 +62,9 @@ To return the relative permalink to another Output Format of a page:
{{ 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).
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.
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/).
{{< code-toggle file=hugo >}}
refLinksErrorLevel = 'warning'
refLinksNotFoundURL = '/some/other/url'
{{< /code-toggle >}}

19
docs/content/en/functions/urls/RelURL.md
View File

@@ -1,21 +1,16 @@
---
title: urls.RelURL
linkTitle: relURL
description: Returns a relative URL.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [relURL]
returnType: template.HTML
related:
- functions/urls/AbsLangURL
- functions/urls/AbsURL
- functions/urls/RelLangURL
returnType: string
signatures: [urls.RelURL INPUT]
relatedFunctions:
- urls.AbsLangURL
- urls.AbsURL
- urls.RelLangURL
- urls.RelURL
aliases: [/functions/relurl]
---

98
docs/content/en/functions/urls/URLize.md
View File

@@ -1,69 +1,63 @@
---
title: urls.URLize
linkTitle: urlize
description: Takes a string, sanitizes it for usage in URLs, and converts spaces to hyphens.
categories: [functions]
description: Returns the given string, sanitized for usage in a URL.
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [urlize]
related:
- functions/urls/Anchorize
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:
{{% include "/functions/urls/_common/anchorize-vs-urlize.md" %}}
{{< 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"]
## Example
Use the `urlize` function to create a link to a [term] page.
Consider this site configuration:
{{< code-toggle file=hugo >}}
[taxonomies]
author = 'authors'
{{< /code-toggle >}}
The following might be used as a partial within a [single page template][singletemplate]:
And this front matter:
{{< 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 >}}
{{< code-toggle file=content/books/les-miserables.md fm=true >}}
title = 'Les Misérables'
authors = ['Victor Hugo']
{{< /code-toggle >}}
The preceding partial would then output to the rendered page as follows:
The published site will have this structure:
```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>
```text
public/
├── authors/
│ ├── victor-hugo/
│ │ └── index.html
│ └── index.html
├── books/
│ ├── les-miserables/
│ │ └── index.html
│ └── index.html
└── index.html
```
[singletemplate]: /templates/single-page-templates/
To create a link to the term page:
```go-html-template
{{ $taxonomy := "authors" }}
{{ $term := "Victor Hugo" }}
{{ with index .Site.Taxonomies $taxonomy (urlize $term) }}
<a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a>
{{ end }}
```
To generate a list of term pages associated with a given content page, use the [`GetTerms`] method on a `Page` object.
[`GetTerms`]: /methods/page/getterms/
[term]: /getting-started/glossary/#term

13
docs/content/en/functions/urls/_common/_index.md Normal file
View File

@@ -0,0 +1,13 @@
---
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.
-->

35
docs/content/en/functions/urls/_common/anchorize-vs-urlize.md Normal file
View File

@@ -0,0 +1,35 @@
---
# 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
```

12
docs/content/en/functions/urls/_index.md Normal file
View File

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