Is there a way to render the {{< relref .. >}} shortcode in Page front-matter variiables

Hello,

I am aware that markdownify or $.Page.RenderString cannot render the {{< relref .. >}} shortcodes in strings. But I want to check if anyone has figured out a workaround or something to do that.

In my post writing flow, I add post updates to a front-matter array-type variable and that can contain relrefs referring to other posts on the same website. It would be cool if those relrefs can be rendered by Hugo. For now, I am using hard-coded URLs instead of relrefs when referring to other posts in those front-matter variables.

Intended example use

+++
title = "my post"
[logbook]
  [logbook._toplevel]
    [[logbook._toplevel.notes]]
      timestamp = 2022-04-15T00:00:00-04:00
      note = """
  This post was re-exported today to get better `info:` link exports as
  described in [a newer post]({{< relref "that-other-post" >}}).
  """

So, the relref shortcode is one of the things I’m not … totally happy about in Hugo, which I kind of hoped would silently varnish like an old oak table once we got link render hooks … That sad, if you do:

+++
title = "my post"
[logbook]
  [logbook._toplevel]
    [[logbook._toplevel.notes]]
      timestamp = 2022-04-15T00:00:00-04:00
      note = """
  This post was re-exported today to get better `info:` link exports as
  described in [a newer post]({/that-other-post).
  """

And create a render hook that mimics what relref is doing (should not be too hard, there are plenty of examples floating around), and then use $.Page.RenderString to render the note.

OK, I see what you mean. This would mean a big change in the ox-hugo exporter I have been using. relref and figure are the only 2 shortcodes it depends on.

I personal appreciate the availability of relref because Hugo deals with the link validity and resolution under the hood.

I’ll add a long term goal to get rid of the relref shortcode in exports — the main problem is that all the ox-hugo users will need to add the special link render hook to their sites and themes.


Alternatively, can $.Page.RenderString be updated to treat the relref shortcode as a special element and resolve the link?

No, that’s not going to happen. $.Page.RenderString will eventually get shortcode support, though.

Well, that will be great! I’ll wait for that, and also start planning on how to stop exporting relref’s.

One problem I see with the render hooks is that we will end up with clashes where a theme might be doing something special with those hooks whereas a user would need to add a hook just to mimick the relref behavior. I am unable to see the link render hook as a solution that will Just Work out of the box for all the users.

Yea, maybe, but in my head

  • The main motivation behind render hooks was to make it possible to resolve resources (links, images) behind the scenes while preserving more or less the Markdown in its standard form (browsable on GitHub etc.)
  • I understand that it’s tempting to use it to … add markup and shit, but …
  • relref/ref is stil there, but I find it rather … intrusive.

I’m using relref a lot because it’s convenient to check the links and get a relative path on a bigger site. But I do get your point. It’s annoying to always have to use a shortcode inside of Markdown. So I’m considering to include the functionality into my render-link hook.

In your example for GitHub-compatible links, you’re using .Page.GetPage to retrieve relative URLs.
Is there a reason to prefer this method over the relref function?

I have mentioned the reason above: Portable links/markdown. Images/links that also works on GitHub etc.

That may not be important in many situations, but in common Hugo documentation sites hosted on GitHub, I think it’s a big deal.

Yes, sorry, I didn’t make myself clear enough. I meant the relref function for templates. But probably it won’t work inside a hook, I suppose.

OK, now I get it. No, there is no reason for that. I guess I forgot that it was there …

1 Like

@Georg

The ref and relref functions emit a warning or error (configurable) when the path cannot be resolved to a page.

The .GetPage method gives you more control over what happens when a path cannot be resolved to a page.

1 Like