HUGO
News Docs Themes Community GitHub

urls.RelRef

Returns the relative URL of the page with the given path, language, and output format.

Syntax

urls.RelRef PAGE PATH
urls.RelRef PAGE OPTIONS

Returns

string

Alias

relref

Usage

The relref function takes two arguments:

  1. The context for resolving relative paths (typically the current page).
  2. 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:

{{ relref . "/books/book-1" }} → /en/books/book-1/

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

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

{{ $opts := dict "path" "/books/book-1" "lang" "de" "outputFormat" "json" }}
{{ relref . $opts }} → /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"
}