urls.Ref
Returns the absolute URL of the page with the given path, language, and output format.
Syntax
urls.Ref PAGE PATH
urls.Ref PAGE OPTIONS
Returns
string
Alias
ref
Usage
The ref
function takes two arguments:
- The context for resolving relative paths (typically the current page).
- Either the target page’s path or an options map (see below).
Options
- path
- (
string
) The path to the target page. Paths without a leading slash (/
) are resolved first relative to the current page, and then relative to the rest of the site. - lang
- (
string
) The language of the target page. Default is the current language. Optional. - outputFormat
- (
string
) The output format of the target page. Default is the current output format. Optional.
Examples
The following examples show the rendered output for a page on the English version of the site:
{{ ref . "/books/book-1" }} → https://example.org/en/books/book-1/
{{ $opts := dict "path" "/books/book-1" }}
{{ ref . $opts }} → https://example.org/en/books/book-1/
{{ $opts := dict "path" "/books/book-1" "lang" "de" }}
{{ ref . $opts }} → https://example.org/de/books/book-1/
{{ $opts := dict "path" "/books/book-1" "lang" "de" "outputFormat" "json" }}
{{ ref . $opts }} → https://example.org/de/books/book-1/index.json
Error handling
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.
refLinksErrorLevel: warning
refLinksNotFoundURL: /some/other/url
refLinksErrorLevel = 'warning'
refLinksNotFoundURL = '/some/other/url'
{
"refLinksErrorLevel": "warning",
"refLinksNotFoundURL": "/some/other/url"
}
Last updated:
March 5, 2025
:
content: Remove "related" array from function and method pages (2fcd21ee5)
Improve this page