urls.Ref

Usage

The urls.Ref function returns the absolute 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 a relative URL, use the urls.RelRef 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.Ref . "/books/book-1" }} → https://example.org/en/books/book-1/

Passing an options map:

{{ $opts := dict "path" "/books/book-1" }}
{{ urls.Ref . $opts }} → https://example.org/en/books/book-1/

{{ $opts := dict "path" "/books/book-1" "lang" "de" }}
{{ urls.Ref . $opts }} → https://example.org/de/books/book-1/

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