Ref shortcode
To override Hugo’s embedded ref shortcode, copy the source code to a file with the same name in the layouts/shortcodes directory.
When working with Markdown, this shortcode is obsolete. Instead, use a link render hook that resolves the link destination using the GetPage method on the Page object. You can either create your own, or simply enable the embedded link render hook. The embedded link render hook is automatically enabled for multilingual single-host projects.
Usage
The ref shortcode accepts either a single positional argument (the path) or one or more named arguments, as listed below.
Arguments
- 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 ref shortcode typically provides the destination for a Markdown link.
Always use Markdown notation notation when calling this shortcode.
The following examples show the rendered output for a page on the English version of the site:
[Link A]({{% ref "/books/book-1" %}})
[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" %}})Rendered:
<a href="https://example.org/en/books/book-1/">Link A</a>
<a href="https://example.org/en/books/book-1/">Link B</a>
<a href="https://example.org/de/books/book-1/">Link C</a>
<a href="https://example.org/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 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"
}