HUGO
Menu
GitHub 90498 stars Mastodon

urls.RelRef

Returns the relative URL of the page with the given logical path.
Syntax
urls.RelRef PAGE PATH
urls.RelRef PAGE OPTIONS
Returns
string
Alias
relref

Usage

The urls.RelRef function returns the relative URL of the page with the given logical path. By default, the URL is for the target page in the current language. To return the URL for a different language or output format, pass an options map instead of a path.

To return an absolute URL, use the urls.Ref function instead.

By default, Hugo fails the build if it cannot resolve the logical path. To log a warning instead, set refLinksErrorLevel to warning in your project configuration. To return a specific URL when Hugo cannot resolve the logical path, set refLinksNotFoundURL. Otherwise, Hugo returns an empty string.

refLinksErrorLevel: warning
refLinksNotFoundURL: /not-found/
refLinksErrorLevel = 'warning'
refLinksNotFoundURL = '/not-found/'
{
   "refLinksErrorLevel": "warning",
   "refLinksNotFoundURL": "/not-found/"
}

Arguments

PAGE
(page.Page) The page used to resolve relative paths and to determine the default language.
PATH
(string) The logical path of the target page, as described in the path option.
OPTIONS
(map) The logical path, language, and output format of the target page. See options.

Options

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 if its permalinkable setting is true and the target page has that output format, otherwise the primary output format of the target page. Optional.
path
(string) The logical path of the target page. The path resolution rules apply. Required.

Examples

These examples use a page in the English site of a multilingual project:

{{ urls.RelRef . "/books/book-1" }} → /en/books/book-1/

Passing an options map:

{{ $opts := dict "path" "/books/book-1" }}
{{ urls.RelRef . $opts }} → /en/books/book-1/

{{ $opts := dict "path" "/books/book-1" "lang" "de" }}
{{ urls.RelRef . $opts }} → /de/books/book-1/

{{ $opts := dict "path" "/books/book-1" "lang" "de" "outputFormat" "json" }}
{{ urls.RelRef . $opts }} → /de/books/book-1/index.json