Ref

Insert a permalink to the given page reference using the 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 the Markdown content format, this shortcode has become largely redundant. Its functionality is now primarily handled by link render hooks, specifically the embedded one provided by Hugo. This hook effectively addresses all the use cases previously covered by this shortcode.

The ref shortcode returns the permalink of the given page reference.

Example usage:

[Post 1]({{% ref "/posts/post-1" %}})
[Post 1]({{% ref "/posts/post-1.md" %}})
[Post 1]({{% ref "/posts/post-1#foo" %}})
[Post 1]({{% ref "/posts/post-1.md#foo" %}})

Rendered:

<a href="https://example.org/posts/post-1/">Post 1</a>
<a href="https://example.org/posts/post-1/">Post 1</a>
<a href="https://example.org/posts/post-1/#foo">Post 1</a>
<a href="https://example.org/posts/post-1/#foo">Post 1</a>

Always use Markdown notation notation when calling this shortcode.

Last updated: February 17, 2025 : all: Change shortcode usage and design to prevent invalid HTML (0fca8ef25)

Improve this page