Short code to support references in hugo blog post

example_post.md

+++ date = 2025-04-20 title = "Reference Test Page" description = "" slug = "" authors = [] tags = [] categories = [] externalLink = "" series = [] draft = true +++

{{< refdef tag="restir_di" title="Spatiotemporal reservoir resampling for real-time ray tracing with dynamic direct lighting" link="https://research.nvidia.com/publication/2020-07_spatiotemporal-reservoir-resampling-real-time-ray-tracing-dynamic-direct" >}} {{< refdef tag="restir_gi" title="ReSTIR GI: Path Resampling for Real-Time Path Tracing" link="https://research.nvidia.com/publication/2021-06_restir-gi-path-resampling-real-time-path-tracing" >}} {{< refdef tag="restir_gris" title="Generalized Resampled Importance Sampling: Foundations of ReSTIR" link="https://research.nvidia.com/publication/2022-07_generalized-resampled-importance-sampling-foundations-restir" >}} {{< refdef tag="pbrt" title="Physically Based Rendering" link="https://www.pbr-book.org/" >}} {{< refdef tag="lumen" title="Lumen: Real-time Global Illumination in Unreal Engine 5" link="https://advances.realtimerendering.com/s2022/index.html#Lumen" >}}

{{< refdef tag="lumen" title="Lumen: Real-time Global Illumination in Unreal Engine 5 (duplicated)" link="https://advances.realtimerendering.com/s2022/index.html#Lumen" >}}

{{< refdef title="Reference Without a link" >}}

This is the first reference {{< refcite tag="lumen" >}}

This is the second reference {{< refcite tag="pbrt" >}}

This is a broken reference {{< refcite tag="restir" >}}

{{< refshow >}}

refcite.html

{{/* Usage:
   {{< ref tag="tag_of_reference" >}}
*/}}

{{- $tagPrefix := "ref_tag__" -}}
{{- $tag := .Get "tag" -}}
{{- $fullTag := print $tagPrefix $tag -}}

{{- if not $tag }}
  <sup style="color: red;">[ref shortcode missing "tag"]</sup>
{{- else -}}

  {{- $refs := .Page.Scratch.Get "references" | default (dict) -}}
  {{- $ref := index $refs $fullTag | default nil -}}

  {{- if not $ref }}
    <sup style="color: red;">[undefined reference: {{ $tag }}]</sup>
  {{- else -}}

    {{- $refered_id := index $ref "refered_id" -}}

    {{- if ge $refered_id 1073741823 -}}
      {{- $counter := .Page.Scratch.Get "ref-counter" | default 1 -}}
      {{- $refered_id = $counter -}}
      {{- $ref = merge $ref (dict "refered_id" $refered_id) -}}
      {{- $refs = merge $refs (dict $fullTag $ref) -}}
      {{- .Page.Scratch.Set "references" $refs -}}
      {{- .Page.Scratch.Set "ref-counter" (add $counter 1) -}}
    {{- end -}}

    <sup style="font-size: 0.7em; vertical-align: super;"><a href="#ref-{{ $fullTag }}" style="text-decoration: none;">[{{ $refered_id }}]</a></sup>

  {{- end -}}

{{- end -}}

refdef.html

{{/* Usage:
   {{< refdef tag="one_tag" title="article_title" page="post.md" >}}
   {{< refdef tag="other_tag" title="article_title" link="external_link" >}}
*/}}

{{- $tagPrefix := "ref_tag__" -}}

{{/* Initialize or bump the counter */}}
{{- if not (.Page.Scratch.Get "ref_counter") -}}
  {{- .Page.Scratch.Set "ref_counter" 1 -}}
{{- else -}}
  {{- .Page.Scratch.Set "ref_counter" (add (.Page.Scratch.Get "ref_counter") 1) -}}
{{- end -}}

{{- $tag := .Get "tag" | default (printf "anonymous_ref_tag-%d" (.Page.Scratch.Get "ref_counter")) -}}
{{- $fullTag := print $tagPrefix $tag -}}
{{- $title := .Get "title" -}}

{{- $page := .Get "page" -}}
{{- $link := "" -}}

{{- if $page -}}
  {{- $pageObj := .Site.GetPage "page" $page -}}
  {{- if $pageObj -}}
    {{- $link = $pageObj.Permalink -}}
  {{- else -}}
    {{- $link = "" -}}
  {{- end -}}
{{- else if .Get "link" -}}
  {{- $link = .Get "link" -}}
{{- else -}}
  {{- $link = "" -}}
{{- end -}}

{{- $refs := .Page.Scratch.Get "references" | default (dict) -}}

{{- if index $refs $fullTag -}}
  <span style="color: red; font-weight: bold;">[Error: reference tag "{{ $tag }}" already defined]</span>
{{- else -}}
  {{- $counter := .Page.Scratch.Get "refdefine-counter" | default 1073741823 -}}
  {{- $refered_id := add $counter 1 -}}
  {{- .Page.Scratch.Set "refdefine-counter" $refered_id -}}

  {{- $ref := dict "tag" $fullTag "title" $title "link" $link "refered_id" $refered_id -}}
  {{- $refs = merge $refs (dict $fullTag $ref) -}}
  {{- .Page.Scratch.Set "references" $refs -}}
{{- end -}}

refshow.html

{{/* Usage:
   {{< refshow >}}
*/}}

{{- $refs := .Page.Scratch.Get "references" | default (dict) -}}
{{- $tmp_ref_arry := slice -}}

{{- range $key, $val := $refs -}}
  {{- $entry := dict
      "tag" $val.tag
      "title" $val.title
      "link" $val.link
      "refered_id" $val.refered_id
  -}}
  {{- $tmp_ref_arry = $tmp_ref_arry | append $entry -}}
{{- end -}}

<!-- Sort tmp_ref_arry references by their 'refered_id' field -->
{{- $sorted := sort $tmp_ref_arry "refered_id" -}}

<!-- Add the 'References' heading -->
<h1>References</h1>

<div>
  {{- range $i, $ref := $sorted -}}
    <div id="ref-{{ $ref.tag }}">
      [{{ add $i 1 }}] 
      {{- if $ref.link }}
        <!-- If there is a link, display it as a hyperlink -->
        <a href="{{ $ref.link }}" rel="noopener noreferrer">{{ $ref.title }}</a>
      {{- else }}
        <!-- If no link, display title as plain text -->
        {{ $ref.title }}
      {{- end }}
    </div>
  {{- end -}}
</div>

This is a convenience tool for defining references in hugo posts.

Here is how it works.

• Define references at the beginning, rather than at the end. Defining != showing. For each item, we only need tag, title and link/page. Page is for reference to other post of yours.
• Reference to an item with a short code by using their tag, rather than hard coding it with numbers and links.
• At the end of the article, simply do {{< refshow >}} to show all the references articles.

Here are the features it supports.

• References with actual reference first will show earlier in the reference list in the order they are refered first.
• References without actual references will show after those are actually refered in the order they are defined.
• Failing to find the tag will produce obvous error on page
• Reference to a same item will result to the same link
• The reference text will be a link on post, which links to the line of the corresponding reference item
• Reference link supports both external link and other internal hugo post link