docs: Prepare for new sub tree

See #11925
This commit is contained in:
Bjørn Erik Pedersen
2024-01-27 10:47:28 +01:00
parent 1083bf7c08
commit fc7de7136a
1157 changed files with 0 additions and 64232 deletions

View File

@@ -1,67 +0,0 @@
---
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]
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 %}}

View File

@@ -1,66 +0,0 @@
---
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]
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/

View File

@@ -1,37 +0,0 @@
---
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]
aliases: [/functions/anchorize]
---
{{% include "/functions/urls/_common/anchorize-vs-urlize.md" %}}
## Sanitizing logic
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.

View File

@@ -1,30 +0,0 @@
---
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...]
aliases: [/functions/urls.joinpath]
---
{{< new-in 0.112.0 >}}
```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.
[`path.Join`]: /functions/path/join

View File

@@ -1,33 +0,0 @@
---
title: urls.Parse
description: Parses a URL into a URL structure.
categories: []
keywords: []
action:
aliases: []
related: []
returnType: url.URL
signatures: [urls.Parse URL]
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
```

View File

@@ -1,63 +0,0 @@
---
title: urls.Ref
description: Returns the absolute permalink to a page at the given path.
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
aliases: [/functions/ref]
---
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
{{ ref . "about" }}
{{ ref . "about#anchor" }}
{{ ref . "about.md" }}
{{ ref . "about.md#anchor" }}
{{ ref . "#anchor" }}
{{ ref . "/blog/my-post" }}
{{ 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
{{ 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") }}
```
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 >}}

View File

@@ -1,67 +0,0 @@
---
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]
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 %}}

View File

@@ -1,70 +0,0 @@
---
title: urls.RelRef
description: Returns the relative permalink to a page at the given path.
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
aliases: [/functions/relref]
---
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" }}
{{ 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" }}`|`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:
```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") }}
```
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 >}}

View File

@@ -1,66 +0,0 @@
---
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]
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/

View File

@@ -1,63 +0,0 @@
---
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]
aliases: [/functions/urlize]
---
{{% include "/functions/urls/_common/anchorize-vs-urlize.md" %}}
## 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 >}}
And this front matter:
{{< code-toggle file=content/books/les-miserables.md fm=true >}}
title = 'Les Misérables'
authors = ['Victor Hugo']
{{< /code-toggle >}}
The published site will have this structure:
```text
public/
├── authors/
│ ├── victor-hugo/
│ │ └── index.html
│ └── index.html
├── books/
│ ├── les-miserables/
│ │ └── index.html
│ └── index.html
└── index.html
```
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

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