Relref shortcode
When working with Markdown this shortcode is obsolete. Instead, to properly resolve Markdown link destinations, use the embedded link render hook or create your own.
In its default configuration, Hugo automatically uses the embedded link render hook for multilingual single-host projects, specifically when the duplication of shared page resources feature is disabled. This is the default behavior for such projects. If your project or its modules define custom link render hooks, Hugo uses those instead.
You can also configure Hugo to always use the embedded link render hook, use it only as a fallback, or never use it. See details.
Usage
The relref shortcode accepts either a single positional argument (the path) or one or more named arguments, as listed below.
Arguments
path- (
string) The logical path of the target page. The path resolution rules apply: Hugo resolves a path without a leading slash (/) first relative to the current page, then relative to thecontentdirectory. If the path does not contain a slash and Hugo has not found the page, Hugo searches for a page with the same base name, and fails the build if more than one page matches. 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 relref shortcode typically provides the destination for a Markdown link.
Always use Markdown notation when calling this shortcode.
The following examples show the rendered output for a page on the English version of the site:
[Link A]({{% relref "/books/book-1" %}})
[Link B]({{% relref path="/books/book-1" %}})
[Link C]({{% relref path="/books/book-1" lang="de" %}})
[Link D]({{% relref path="/books/book-1" lang="de" outputFormat="json" %}})Rendered:
<a href="/en/books/book-1/">Link A</a>
<a href="/en/books/book-1/">Link B</a>
<a href="/de/books/book-1/">Link C</a>
<a href="/de/books/book-1/index.json">Link D</a>Error handling
By default, Hugo will throw an error and fail the build if it cannot resolve the logical path. You can change this to a warning in your project configuration, and specify a URL to return when the logical path cannot be resolved.
refLinksErrorLevel: warning
refLinksNotFoundURL: /some/other/url
refLinksErrorLevel = 'warning'
refLinksNotFoundURL = '/some/other/url'
{
"refLinksErrorLevel": "warning",
"refLinksNotFoundURL": "/some/other/url"
}
To override Hugo’s embedded relref shortcode, copy the source code to a file with the same name in the layouts/_shortcodes directory.