Questions about ref/relref

support
1

So I’ve been messing around with Hugo for a while and I’m actually quite enjoying the experience. However, there is one thorny corner that I’m a little lost on…ref and relref.

All instances of ref and relref I can find in the official documentation cover how to use these functions in the context of a markdown document, and they use them like this:

{{< ref "document" >}}

However, I was encountering issues with this setup, and I had to find out the hard way that I had to use the following invocation if I was outside the context of a markdown page:

{{ ref . "document" }}

I’m not exactly sure why I need to pass the first parameter - I just was messing around with the command until I got it to work.

So here are my questions:

  1. What exactly does {{< >}} do, why does it work in the context of Markdown, and why doesn’t it work outside of it?
  2. Why isn’t the “outside of markdown” invocation of ref or relref covered anywhere in the docs?
  3. Is it possible to link to a list page? I’ve tried stuff like <a href="{{ relref . "news/_index.md" }}">More News...</a>, to link to an index page, but I just get an error.
2

The {{< >}} syntax indicates a shortcode.

Shortcodes are not usable in Go templates themselves - they serve as a way to give some of the power of the template to a markdown or other content file.

The {{ ref . "whatever" }} form you are using is actually using the template function named ref whereas {{< ref "whatever" >}} is using the internal shortcode that is also named ref (and if you look at it’s implementation, it is a very basic wrapper around the ref function).

The template function ref is documented here: https://gohugo.io/templates/functions/#urls
The shortcode ref is documented here: https://gohugo.io/extras/shortcodes/#ref-relref

1 Like