titleref: Referencing Hugo posts by their titles

relref shortcode #

Hugo has a built-in shortcode relref that gets relative links  There’s also a ref shortcode which creates absolute links. ref can be used wherever relref is used. to other posts by using their url. In Hugo lingo, a post’s url consists of the post’s section and slug  This post’s section is posts and slug is titleref-referencing-hugo-posts-by-their-titles. So the url is posts/titleref-referencing-hugo-posts-by-their-titles. .

This page’s relative link can be fetched by using {{< relref "posts/titleref-referencing-hugo-posts-by-their-titles" >}}. If a post’s slug is unique across all the posts, its section part can be skipped. So the same relref can be written as {{< relref "titleref-referencing-hugo-posts-by-their-titles" >}} and that will still return this same link.

Problem Statement

The issue with relref is that it returns only the link — the description still needs to be written manually. I typically use a post’s title as description when I link to it. So the full link with description will look like this when writing in Org mode  In Markdown, the same link will look like this: [titleref: Referencing Hugo posts by their titles]({{< relref "titleref-referencing-hugo-posts-by-their-titles" >}}). for exporting using ox-hugo: [[@@hugo:{{< relref "titleref-referencing-hugo-posts-by-their-titles" >}}@@][titleref: Referencing Hugo posts by their titles]].

You can see how impractical and verbose that is!

If you write your posts in Markdown, you can jump to the titleref shortcode section.

relref Org macro #

An Org macro can help a little over here.

#+macro: relref @@hugo:[@@ $1 @@hugo:]({{< relref "$2" >}})@@

With this macro, that same relref link can be rewritten as {{{relref(titleref: Referencing Hugo posts by their titles,titleref-referencing-hugo-posts-by-their-titles)}}}.

It’s a bit less verbose compared to using the shortcode directly, but I still wasn’t happy with the redundancy.

titleref shortcode #

And so I thought that it should be pretty simple to specify just the title of post that I want to link, and let Hugo derive the post’s permalink — and it was simple, by using this custom  A user can add custom shortcodes or override the default Hugo shortcodes by putting them in the layouts/shortcodes/ directory of the site or theme repo. shortcode!

An astute Org mode user might think that this idea looks like the [[*Heading]] syntax supported by Org, and they would be right! This titleref idea is inspired by that Org mode feature.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

{{- $title_anchor := (.Get 0) -}}
{{- $title := trim (index (split $title_anchor "#") 0) " " -}}
{{- $anchor := trim (index (split $title_anchor "#") 1) " " -}}
{{- $desc := (.Get 1) | markdownify -}}
{{- $filtered := where site.RegularPages "Title" $title -}}
{{- $first_match := index $filtered 0 -}}
{{- with $first_match -}}
    {{- if $anchor -}}
        {{- $anchor = printf `#%s` $anchor -}}
    {{- end -}}
    {{- $anchor = $anchor | default "" -}}
    {{- $desc = $desc | default .Title -}}
    {{- (printf `<a href="%s%s">%s</a>` .RelPermalink $anchor $desc) | safeHTML -}}
{{- else -}}
    {{- (errorf `%s: Page titled "%s" not found` .Position $title) -}}
{{- end -}}

This shortcode is designed to take up to two arguments:

title (+anchor)

The first argument can be just the title of the post that we want to link (e.g. “My post”). Optionally, it can also be followed by an anchor in that post, separated by “#” (e.g. “My post#some-heading”).

(description)

The second argument is optional, and it’s the link description. If this argument is not set, the description is set to the post’s title.

titleref Org macro #

But the fun doesn’t end here for an Org mode user! 😃

I do not prefer using Hugo shortcodes directly in my Org source. So I created an Org macro to wrap this shortcode.

#+macro: titleref @@hugo:{{< titleref "$1" "@@ $2 @@hugo:" >}}@@

Now {{{titleref(titleref: Referencing Hugo posts by their titles,)}}} will export to titleref: Referencing Hugo posts by their titles.

Here are some example uses of this macro:

• {{{titleref(TITLE,)}}} – Link to a page with that TITLE and set the link description to be the same as the TITLE.
• {{{titleref(TITLE,DESC)}}} – Link to a page with that TITLE, with DESC as description.
• {{{titleref(TITLE#ANCHOR,DESC)}}} – Link to an ANCHOR in a page with that TITLE, with DESC as description.

Summary #

By using the titleref shortcode (or Org macro) instead of relref, we now have a tremendous reduction of redundancy.

Before

• Org mode: {{{relref(titleref: Referencing Hugo posts by their titles,titleref-referencing-hugo-posts-by-their-titles)}}}
• Markdown: [titleref: Referencing Hugo posts by their titles]({{< relref "titleref-referencing-hugo-posts-by-their-titles" >}})

Now

• Org mode: {{{titleref(titleref: Referencing Hugo posts by their titles,)}}}
• Markdown: {{< titleref "titleref: Referencing Hugo posts by their titles" >}}