relref: provide shortcodes to lift certain restrictions #864

exampleSite/config/_default/params.toml

@@ -337,6 +337,18 @@ imageEffects.shadow = false
 # Links
 # These options configure how links are displayed.
 
+# Wether to use Hugo's default relref shortcode implementation
+# Default: false
+# Since the theme provides a link render hook, the usage of the relref shortcode
+# is obsolete. If a site still uses that shortcode, it fails to generate a
+# correct link if the baseURL is configured with a subdirectory.
+# The theme provides an overriden relref shortcode that also works in the
+# above setup. Nevertheless there can be cases where the user want to fallback
+# to the default implementation, which can be achieved by setting this option to
+# true.
+# See discussion in https://github.com/McShelby/hugo-theme-relearn/discussions/862
+useDefaultRelref = false
+
 # What to do when local page link is not resolved.
 # Default: ""
 # You can control what should happen if a local link can not be resolved to a

exampleSite/content/basics/migration/_index.en.md

@@ -26,6 +26,10 @@ This document shows you what's new in the latest release and flags it with one o
 
 - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The [`openapi` shortcode](shortcodes/openapi) is now able to resolve links to resources as well as to files in the file system (the old behavior). You can configure to generate warnings or errors during build by setting `openapi.errorlevel` to either `warning` or `error` in your `hugo.toml` if a path can not be resolved.
 
+- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The theme now comes with its own overridden version of the `relref` shortcode.
+
+  While the usage of `relref` is obsolete and discouraged by Hugo for a while, existing installations may use it. In configurations using a `baseURL` with a subdirectory, the default `relref` implementation of Hugo was failing, so an overridden shortcode was necessary.
+
 ---
 
 ## 6.0.0 (2024-04-27) {#600}

layouts/shortcodes/relref.html

@@ -0,0 +1,5 @@
+{{- if site.Params.useDefaultRelref }}
+	{{- relref . .Params }}
+{{- else }}
+	{{- .Get "path" | default (.Get 0) }}
+{{- end }}