link: warn if fragment is not found #823

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

@@ -20,6 +20,8 @@ This document shows you what's new in the latest release and flags it with one o
 
 ## 5.27.0.beta (XXXX-XX-XX) {#5270}
 
+- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} If the theme is configured to to generate warnings or errors during build by setting `image.errorlevel` to either `warning` or `error` in your `hugo.toml`, it will now also generate output if a link fragment is not found in the target page.
+
 - {{% badge style="note" title=" " %}}Change{{% /badge %}} The [dependency loader](basics/customization#own-shortcodes-with-javascript-dependencies) was made more versatile.
 
   The configuration in your `hugo.toml` does not require the `location` parameter anymore. If you still use it, the theme will work as before but will generate a warning. So you don't need to change anything, yet.

layouts/partials/shortcodes/link.html

@@ -63,6 +63,14 @@
       {{- $href = printf "%s?%s" $href . }}
     {{- end }}
     {{- with $u.Fragment }}
+      {{- $ctx := dict
+        "contentPath" $page.File.Filename
+        "errorLevel" $page.Site.Params.link.errorlevel
+        "page" $linkPage
+        "parsedURL" $u
+        "renderHookName" "link"
+      }}
+      {{- partial "inline/h-rh-l/validate-fragment.html" $ctx }}
       {{- $href = printf "%s#%s" $href . }}
     {{- end }}
   {{- else }}
@@ -79,4 +87,56 @@
     {{- if $v }}
       {{- printf " %s=%q" $k $v | safeHTMLAttr }}
     {{- end }}
-  {{- end }}>{{ $content | safeHTML }}</a>
+  {{- end }}>{{ $content | safeHTML }}</a>
+
+{{- define "partials/inline/h-rh-l/validate-fragment.html" }}
+  {{- /*
+  Validates the fragment portion of a link destination.
+
+  @context {string} contentPath The page containing the link.
+  @context {string} errorLevel The error level when unable to resolve destination; ignore (default), warning, or error.
+  @context {page} page The page corresponding to the link destination
+  @context {struct} parsedURL The link destination parsed by urls.Parse.
+  @context {string} renderHookName The name of the render hook.
+  */}}
+
+  {{- /* Initialize. */}}
+  {{- $contentPath := .contentPath }}
+  {{- $errorLevel := .errorLevel }}
+  {{- $p := .page }}
+  {{- $u := .parsedURL }}
+  {{- $renderHookName := .renderHookName }}
+
+  {{- /* Validate. */}}
+  {{- with $u.Fragment }}
+    {{- if $p.Fragments.Identifiers.Contains . }}
+      {{- if gt ($p.Fragments.Identifiers.Count .) 1 }}
+        {{- $msg := printf "%q: duplicate heading ID %q found" $contentPath . }}
+        {{- if eq $errorLevel "warning" }}
+          {{- warnf $msg }}
+        {{- else if eq $errorLevel "error" }}
+          {{- errorf $msg }}
+        {{- end }}
+      {{- end }}
+    {{- else }}
+      {{- /* Determine target path for warning and error message. */}}
+      {{- $targetPath := "" }}
+      {{- with $p.File }}
+        {{- $targetPath = .Path }}
+      {{- else }}
+        {{- $targetPath = .Path }}
+      {{- end }}
+      {{- /* Set common message. */}}
+      {{- $msg := printf "%q: heading ID %q not found in %q" $contentPath . $targetPath }}
+      {{- if eq $targetPath $contentPath }}
+        {{- $msg := printf "%q: heading ID %q not found" $contentPath . }}
+      {{- end }}
+      {{- /* Throw warning or error. */}}
+      {{- if eq $errorLevel "warning" }}
+        {{- warnf $msg }}
+      {{- else if eq $errorLevel "error" }}
+        {{- errorf $msg }}
+      {{- end }}
+    {{- end }}
+  {{- end }}
+{{- end }}