link: link resolving stopped working in certain configurations #882

Author: McShelby

exampleSite/config/_default/params.toml

@@ -343,13 +343,11 @@ imageEffects.shadow = false
 # 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.
+# correct links if the baseURL is configured with a subdirectory and relativeURLs=false.
 # 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.
+# above setup but must manually be activated by setting this option to true.
 # See discussion in https://github.com/McShelby/hugo-theme-relearn/discussions/862
-useDefaultRelref = false
+disableDefaultRelref = false
 
 # What to do when local page link is not resolved.
 # Default: ""

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

@@ -30,7 +30,16 @@ 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 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.
+  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, and having `relativeURLs=false` (the default) Hugo's standard `relref` implementation was failing.
+
+  The shortcode is deactivated by default and can be activated by setting
+
+    {{< multiconfig file=hugo >}}
+    [params]
+      disableDefaultRelref = true
+    {{< /multiconfig >}}
+
+  in your `hugo.toml`. Only do this if your site fulfills **all of the above assumptions**.
 
 ---
 

layouts/shortcodes/relref.html

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