HUGO
Menu
GitHub 90498 stars Mastodon

Ref

Returns the absolute URL of the page with the given logical path.
Syntax
SHORTCODE.Ref OPTIONS
Returns
string

Usage

The Ref method on a Shortcode object 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, set the lang or outputFormat option.

Unlike the urls.Ref function, the Ref method accepts only an options map, not a path. To return a relative URL, use the RelRef method 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/"
}

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 shortcode called from a page in the English site of a multilingual project:

{{ $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