mirror/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2025-08-23 21:53:09 +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

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 >}}