Page References in Hugo

Creating page references in Hugo with shortcodes

There are special shortcodes that tell Hugo to generate the proper link(s) to other pages in your site, or other sections on the current page.

I originally learned this when I wanted to include a link to another post I’d written. I used a reference shortcode (ref) for this:

[Querying PowerPlatform API via. Powershell]( {{< ref "powershell-powerplatform-api.md" >}})

Links to other artifacts in your site can be done with ref (reference) or relref (relative reference). The only difference between them is whether the resulting URL is absolute (http://site.com/about/) or relative (/about/). The ref and relref shortcodes require a single parameter: the path to a content document, with or without a file extension, with or without an anchor. Hugo will try to match the parameter to content in your site. The relref shortcode is handy when you have two pages with the same name, but in different locations, so that Hugo knows which one you want to refer to.

Links to a heading on the current page, or a completely difference page, can be specified with an anchor, which are specified with a pound/hashtag symbol (#).
Link to a heading on the current page: {{< ref "#reference" >}}
Link to a heading on a different page: {{< ref "document.md#reference" >}}

This can all be found in the official Hugo documentation Shortcodes for creating links to documents

Another shortcode trick I learned when writing this post is that escaping curly braces {{ in Hugo can be tricky when using the escape character. Using the backslash will result in some variation of this:
\{{< myshortcode >\}}

A simple way to escape this is by adding /* after the opening < and adding */ after the closing >.
{{</*/* myshortcode */>}} will produce {{< shortcode >}}

Licensed under CC BY-NC-SA 4.0
Built with Hugo
Theme Stack designed by Jimmy