urls.Ref

Usage

The ref 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:

{{ 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"
}