HUGO
Menu
GitHub 90486 stars Mastodon

Ref shortcode

Insert the absolute URL of the page with the given logical path using the ref shortcode.

Usage

The ref shortcode inserts 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 insert the URL for a different language or output format, use named arguments.

With Markdown, this shortcode is obsolete. To resolve Markdown link destinations, use the embedded link render hook or create your own.

By default, Hugo uses the embedded link render hook for multilingual single-host projects where the duplication of shared page resources feature is disabled, which is the default for those projects. If your project or its modules define custom link render hooks, Hugo uses those instead. To change this behavior, set renderHooks.link.useEmbedded to always, fallback, or never.

To insert a relative URL, use the relref shortcode instead.

Use the ref shortcode to provide the destination of a Markdown link or image. Always call the shortcode with Markdown notation, as shown in the examples below. With Markdown notation, Hugo inserts the URL before rendering the Markdown, so link and image render hooks receive the URL as the destination. With standard notation, render hooks receive a placeholder instead of the URL.

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

To override Hugo’s embedded ref shortcode, copy the source code to a file with the same name in the layouts/_shortcodes directory.

Arguments

The ref shortcode accepts either a single positional argument, the logical path of the target page, or named arguments. Do not mix positional and named arguments.

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:

content/example.md
[Link A]({{% ref "/books/book-1" %}})

Hugo renders this to:

<p><a href="https://example.org/en/books/book-1/">Link A</a></p>

With named arguments:

content/example.md
[Link B]({{% ref path="/books/book-1" %}})

[Link C]({{% ref path="/books/book-1" lang="de" %}})

[Link D]({{% ref path="/books/book-1" lang="de" outputFormat="json" %}})

Hugo renders this to:

<p><a href="https://example.org/en/books/book-1/">Link B</a></p>
<p><a href="https://example.org/de/books/book-1/">Link C</a></p>
<p><a href="https://example.org/de/books/book-1/index.json">Link D</a></p>