blogs/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2026-08-24 23:38:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

Make relURL and related functions consistent (#1895)

Browse Source 
This addresses changes made in:
https://github.com/gohugoio/hugo/pull/10002

Closes #469
This commit is contained in:
Joe Mooring
2022-11-16 22:58:11 -08:00
committed by GitHub
parent f12180207a
commit 11977b96f3
4 changed files with 187 additions and 97 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/en/functions/abslangurl.md
+49 -15
View File
@@ -1,27 +1,61 @@
---
title: absLangURL
description: Adds the absolute URL with correct language prefix according to site configuration for multilingual.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
description: Returns an absolute URL with a language prefix, if any.
categories: [functions]
menu:
docs:
parent: "functions"
keywords: [multilingual,i18n,urls]
parent: functions
keywords: [urls, multilingual,i18n]
signature: ["absLangURL INPUT"]
workson: []
hugoversion:
relatedfuncs: [relLangURL]
deprecated: false
aliases: []
---
Both `absLangURL` and [`relLangURL`](/functions/rellangurl/) are similar to their [`absURL`](/functions/absurl/) and [`relURL`](/functions/relurl) relatives but will add the correct language prefix when the site is configured with more than one language.
Use this function with both monolingual and multilingual configurations. The URL returned by this function depends on:
So for a site `baseURL` set to `https://example.com/hugo/` and the current language is `en`:
- 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
```
{{ "blog/" | absLangURL }} → "https://example.com/hugo/en/blog/"
{{ "blog/" | relLangURL }} → "/hugo/en/blog/"
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 %}}
content/en/functions/absurl.md
+44 -33
View File
@@ -1,50 +1,61 @@
---
title: absURL
description: Creates an absolute URL based on the configured baseURL.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
description: Returns an absolute URL.
categories: [functions]
menu:
docs:
parent: "functions"
parent: functions
keywords: [urls]
signature: ["absURL INPUT"]
workson: []
hugoversion:
relatedfuncs: [relURL]
deprecated: false
aliases: []
---
Both `absURL` and `relURL` consider the configured value of `baseURL` in your site's [`config` file][configuration]. Given a `baseURL` set to `https://example.com/hugo/`:
With multilingual configurations, use the [`absLangURL`] function instead. The URL returned by this function depends on:
```
{{ "mystyle.css" | absURL }} → "https://example.com/hugo/mystyle.css"
{{ "mystyle.css" | relURL }} → "/hugo/mystyle.css"
{{ "http://gohugo.io/" | relURL }} → "http://gohugo.io/"
{{ "http://gohugo.io/" | absURL }} → "http://gohugo.io/"
- 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
```
The last two examples may look strange but can be very useful. For example, the following shows how to use `absURL` in [JSON-LD structured data (SEO)][jsonld], where some of your images for a piece of content may or may not be hosted locally:
With `baseURL = https://example.org/docs/`
{{< code file="layouts/partials/schemaorg-metadata.html" download="schemaorg-metadata.html" >}}
<script type="application/ld+json">
{
"@context" : "http://schema.org",
"@type" : "BlogPosting",
"image" : {{ apply .Params.images "absURL" "." }}
}
</script>
{{< /code >}}
```go-html-template
{{ absURL "" }} → https://example.org/docs/
{{ absURL "articles" }} → https://example.org/docs/articles
{{ absURL "style.css" }} → https://example.org/docs/style.css
```
The above uses the [apply function][] and also exposes how the Go template parser JSON-encodes objects inside `<script>` tags. See [the safeJS template function][safejs] for examples of how to tell Hugo not to escape strings inside such tags.
### Input begins with a slash
{{% note "Ending Slash" %}}
`absURL` and `relURL` are smart about missing slashes, but they will *not* add a closing slash to a URL if it is not present.
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 %}}
[apply function]: /functions/apply/
[configuration]: /getting-started/configuration/
[jsonld]: https://developers.google.com/search/docs/guides/intro-structured-data
[safejs]: /functions/safejs
[`absLangURL`]: /functions/abslangurl/
content/en/functions/relLangURL.md
+50 -17
View File
@@ -1,29 +1,62 @@
---
title: relLangURL
description: Adds the relative URL with correct language prefix according to site configuration for multilingual.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
keywords: [multilingual,i18n,urls]
description: Returns a relative URL with a language prefix, if any.
categories: [functions]
menu:
docs:
parent: "functions"
parent: functions
keywords: [urls, multilingual,i18n]
signature: ["relLangURL INPUT"]
workson: []
hugoversion:
relatedfuncs: []
deprecated: false
aliases: []
---
`absLangURL` and `relLangURL` functions are similar to their [`absURL`](/functions/absurl/) and [`relURL`](/functions/relurl/) relatives but will add the correct language prefix when the site is configured with more than one language. (See [Configure Languages][multiliconfig].)
Use this function with both monolingual and multilingual configurations. The URL returned by this function depends on:
So for a site `baseURL` set to `https://example.com/hugo/` and the current language is `en`:
- Whether the input begins with a slash
- The `baseURL` in site configuration
- The language prefix, if any
```
{{ "blog/" | absLangURL }} → "https://example.com/hugo/en/blog/"
{{ "blog/" | relLangURL }} → "/hugo/en/blog/"
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
```
[multiliconfig]: /content-management/multilingual/#configure-languages
### 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 %}}
content/en/functions/relurl.md
+44 -32
View File
@@ -1,49 +1,61 @@
---
title: relURL
description: Creates a baseURL-relative URL.
date: 2017-02-01
publishdate: 2017-02-01
description: Returns a relative URL.
categories: [functions]
menu:
docs:
parent: "functions"
parent: functions
keywords: [urls]
signature: ["relURL INPUT"]
workson: []
hugoversion:
relatedfuncs: [absURL]
deprecated: false
aliases: []
---
Both `absURL` and `relURL` consider the configured value of `baseURL` in your site's [`config` file][configuration]. Given a `baseURL` set to `https://example.com/hugo/`:
With multilingual configurations, use the [`relLangURL`] function instead. The URL returned by this function depends on:
```
{{ "mystyle.css" | absURL }} → "https://example.com/hugo/mystyle.css"
{{ "mystyle.css" | relURL }} → "/hugo/mystyle.css"
{{ "http://gohugo.io/" | relURL }} → "http://gohugo.io/"
{{ "http://gohugo.io/" | absURL }} → "http://gohugo.io/"
- 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
```
The last two examples may look strange but can be very useful. For example, the following shows how to use `absURL` in [JSON-LD structured data for SEO][jsonld] where some of your images for a piece of content may or may not be hosted locally:
With `baseURL = https://example.org/docs/`
{{< code file="layouts/partials/schemaorg-metadata.html" download="schemaorg-metadata.html" >}}
<script type="application/ld+json">
{
"@context" : "https://schema.org",
"@type" : "BlogPosting",
"image" : {{ apply .Params.images "absURL" "." }}
}
</script>
{{< /code >}}
```go-html-template
{{ relURL "" }} → /docs/
{{ relURL "articles" }} → /docs/articles
{{ relURL "style.css" }} → /docs/style.css
```
The above uses the [apply function][] and also exposes how the Go template parser JSON-encodes objects inside `<script>` tags. See [the safeJS template function][safejs] for examples of how to tell Hugo not to escape strings inside of such tags.
### Input begins with a slash
{{% note "Ending Slash" %}}
`absURL` and `relURL` are smart about missing slashes, but they will *not* add a closing slash to a URL if it is not present.
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 %}}
[apply function]: /functions/apply/
[configuration]: /getting-started/configuration/
[jsonld]: https://developers.google.com/search/docs/advanced/structured-data/intro-structured-data
[safejs]: /functions/safejs
[`relLangURL`]: /functions/rellangurl/