From df03dac58f35146443feb48374912e266ca4b2b7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=B6ren=20Weber?= <mail@soeren-weber.de>
Date: Wed, 29 Jan 2025 22:17:39 +0100
Subject: [PATCH] link: add ignore list to checker to skip certain URLs #971

---
 exampleSite/config/_default/params.toml       | 11 ++++++++++
 .../authoring/frontmatter/linking/index.en.md | 12 +++++++++--
 .../frontmatter/linking/index.pir.md          |  4 ++--
 .../frontmatter/reference/frontmatter.toml    | 15 ++++++++++++++
 .../introduction/releasenotes/7/3.en.md       |  4 ++--
 .../introduction/releasenotes/7/4.en.md       |  6 ++++--
 .../partials/_relearn/urlErrorReport.gotmpl   | 20 +++++++++++++++++++
 layouts/partials/menupermalink.gotmpl         | 12 ++---------
 layouts/partials/meta.html                    | 12 ++---------
 layouts/partials/shortcodes/image.html        |  7 +------
 layouts/partials/shortcodes/include.html      |  7 +------
 layouts/partials/shortcodes/link.html         | 10 +++-------
 layouts/partials/shortcodes/openapi.html      |  7 +------
 layouts/partials/version.txt                  |  2 +-
 14 files changed, 75 insertions(+), 54 deletions(-)
 create mode 100644 layouts/partials/_relearn/urlErrorReport.gotmpl

diff --git a/exampleSite/config/_default/params.toml b/exampleSite/config/_default/params.toml
index 9fca83b06a..3beded477e 100644
--- a/exampleSite/config/_default/params.toml
+++ b/exampleSite/config/_default/params.toml
@@ -111,6 +111,17 @@ disableGeneratorVersion = false
 # may not function correctly anymore.
 disableRandomIds = false
 
+# Conditionally ignore errorlevel settings
+# Default: []
+# The theme supports checking referenced address (e.g. with
+# link.errorlevel, image.errorlevel, etc. see below). Sometimes checks lead
+# to console output due to false negatives. You can turn off the checks
+# for individual referenced addresses by defining regular expressions here.
+# The referenced address will be checked against all regexes of this array.
+# If it matches at least one, no output will be written to the console.
+# This array can be expanded in the page's frontmatter.
+errorignore = []
+
 # Additional code dependencies.
 # Default: See hugo.toml of the theme
 # The theme provides a mechanism to load further JavaScript and CSS
diff --git a/exampleSite/content/authoring/frontmatter/linking/index.en.md b/exampleSite/content/authoring/frontmatter/linking/index.en.md
index 4aaef08cd2..8bf2772f0f 100644
--- a/exampleSite/content/authoring/frontmatter/linking/index.en.md
+++ b/exampleSite/content/authoring/frontmatter/linking/index.en.md
@@ -1,8 +1,8 @@
 +++
 categories = ["howto"]
 description = "What options are available for links and images"
-frontmatter = ["externalLinkTarget", "image.errorlevel", "link.errorlevel"]
-options = ["externalLinkTarget", "image.errorlevel", "link.errorlevel"]
+frontmatter = ["errorignore", "externalLinkTarget", "image.errorlevel", "link.errorlevel"]
+options = ["errorignore", "externalLinkTarget", "image.errorlevel", "link.errorlevel"]
 title = "Linking"
 weight = 3
 +++
@@ -31,3 +31,11 @@ Link warnings are also available for the [include](shortcodes/include#enabling-l
 link.errorlevel = 'warning'
 image.errorlevel = 'warning'
 {{< /multiconfig >}}
+
+### Ignoring False Negatives
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} In case you want to use link warnings but are bothered by false negatives, you can configure an ignore list of regular expressions. The referenced address will be checked against all regexes of this list. If the address matches at least one regex, no output will be written to the console. The check uses [Hugo's `findRE` function](https://gohugo.io/functions/strings/findre/).
+
+{{< multiconfig >}}
+errorignore = [ '^/authoring/', '^/configuration/' ]
+{{< /multiconfig >}}
diff --git a/exampleSite/content/authoring/frontmatter/linking/index.pir.md b/exampleSite/content/authoring/frontmatter/linking/index.pir.md
index b96d5381e8..ca11cc8943 100644
--- a/exampleSite/content/authoring/frontmatter/linking/index.pir.md
+++ b/exampleSite/content/authoring/frontmatter/linking/index.pir.md
@@ -1,8 +1,8 @@
 +++
 categories = ["howto"]
 description = "What options are available for links and images"
-frontmatter = ["externalLinkTarget", "image.errorlevel", "link.errorlevel"]
-options = ["externalLinkTarget", "image.errorlevel", "link.errorlevel"]
+frontmatter = ["errorignore", "externalLinkTarget", "image.errorlevel", "link.errorlevel"]
+options = ["errorignore", "externalLinkTarget", "image.errorlevel", "link.errorlevel"]
 title = "Linking"
 weight = 3
 +++
diff --git a/exampleSite/content/authoring/frontmatter/reference/frontmatter.toml b/exampleSite/content/authoring/frontmatter/reference/frontmatter.toml
index 3e0514a93a..ee72822de1 100644
--- a/exampleSite/content/authoring/frontmatter/reference/frontmatter.toml
+++ b/exampleSite/content/authoring/frontmatter/reference/frontmatter.toml
@@ -36,6 +36,21 @@ type = ''
 # Relearn Theme
 # These options are specific to the Relearn theme.
 
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+# General
+# These options are defining general, non visual behavior.
+
+# Conditionally ignore errorlevel settings
+# Default: []
+# The theme supports checking referenced address (e.g. with
+# link.errorlevel, image.errorlevel, etc. see below). Sometimes checks lead
+# to console output due to false negatives. You can turn off the checks
+# for individual referenced addresses by defining regular expressions here.
+# The referenced address will be checked against all regexes of this array.
+# If it matches at least one, no output will be written to the console.
+# This array can be expanded globally in your site's hugo.toml.
+errorignore = []
+
 #++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 # Topbar
 # These options modify the topbar appearance.
diff --git a/exampleSite/content/introduction/releasenotes/7/3.en.md b/exampleSite/content/introduction/releasenotes/7/3.en.md
index 383c737bed..21bb1ecf3c 100644
--- a/exampleSite/content/introduction/releasenotes/7/3.en.md
+++ b/exampleSite/content/introduction/releasenotes/7/3.en.md
@@ -16,8 +16,8 @@ weight = -3
 
 - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The theme supports the new [`markdown` output format](configuration/sitemanagement/outputformats/#markdown-support) which behaves similar in configuration as the `print` output format but allows the Markdown source of a page to be viewed.
 
-  You can see this in action on the above linked page, accessible by clicking the topbar button.
+  You can see this in action on the above linked page, accessible by clicking the {{% button style="transparent" icon="fa-fw fab fa-markdown" %}}{{% /button %}} topbar button.
 
 - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Keyboard support for code blocks was improved so the _copy to clipboard_ button is now reachable by <kbd>TAB</kbd> if `disableHoverBlockCopyToClipBoard=false` was set in the `hugo.toml`.
 
-- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Futher accessibility impovements were made for the _anchor_, _copy to clipboard_ and _mermaid reset_ functionality by using a HTML `button` instead of a `span`.
+- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Further accessibility improvements were made for the _anchor_, _copy to clipboard_ and _mermaid reset_ functionality by using a HTML `button` instead of a `span`.
diff --git a/exampleSite/content/introduction/releasenotes/7/4.en.md b/exampleSite/content/introduction/releasenotes/7/4.en.md
index 69a4a16a81..1fd8270054 100644
--- a/exampleSite/content/introduction/releasenotes/7/4.en.md
+++ b/exampleSite/content/introduction/releasenotes/7/4.en.md
@@ -10,10 +10,12 @@ weight = -4
 
 ### New
 
-- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} If `link.errorlevel` is configured, now also the `pageRef` of a [Hugo menu item](https://gohugo.io/content-management/menus/) and the `menuPageRef` in a page's front matter will be checked for existence.
+- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} If [`link.errorlevel` is configured](authoring/frontmatter/linking/#enabling-link-and-image-link-warnings), now also the `pageRef` of a [Hugo menu item](https://gohugo.io/content-management/menus/) and the `menuPageRef` in a [page's front matter](configuration/sidebar/menus/#displaying-arbitrary-links-in-a-page-menu) will be checked for existence.
+
+- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} You can now [configure an ignore list](authoring/frontmatter/linking/#ignoring-false-negatives) of addresses that should be ignored if an errorlevel test fails. This is configured by setting `errorignore=[]` in your `hugo.toml`. This helps to remove false negatives from the output while still benefitting from the check for all other addresses.
 
 - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The theme supports the new [`source` output format](configuration/sitemanagement/outputformats/#source-support) which behaves similar in configuration as the `markdown` output format but allows the original Markdown source including the front matter of a page to be viewed.
 
-  You can see this in action on the above linked page, accessible by clicking the topbar button.
+  You can see this in action on the above linked page, accessible by clicking the {{% button style="transparent" icon="file-code" %}}{{% /button %}} topbar button.
 
 - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Table headers are sticky now.
diff --git a/layouts/partials/_relearn/urlErrorReport.gotmpl b/layouts/partials/_relearn/urlErrorReport.gotmpl
new file mode 100644
index 0000000000..d2b4573067
--- /dev/null
+++ b/layouts/partials/_relearn/urlErrorReport.gotmpl
@@ -0,0 +1,20 @@
+{{- $pageParam := index .page.Params .param }}
+{{- $siteParam := index .page.Site.Params .param }}
+{{- $errorlevel := or (and $pageParam $pageParam.errorlevel) (and $siteParam $siteParam.errorlevel) }}
+{{- $errorignore := slice | append (.page.Params.errorignore | default slice ) | append (.page.Site.Params.errorignore | default slice ) }}
+{{- if and (eq $errorlevel "warning") (partial "inline/show-error" (dict "errorignore" $errorignore "url" .url)) }}
+	{{- warnf .msg }}
+{{- else if and (eq $errorlevel "error") (partial "inline/show-error" (dict "errorignore" $errorignore "url" .url)) }}
+	{{- errorf .msg }}
+{{- end }}
+
+{{- define "partials/inline/show-error" }}
+	{{- $ret := true }}
+	{{- range .errorignore }}
+		{{- if findRE . $.url 1 }}
+			{{- $ret = false }}
+			{{- break }}
+		{{- end }}
+	{{- end }}
+	{{- return $ret }}
+{{- end }}
\ No newline at end of file
diff --git a/layouts/partials/menupermalink.gotmpl b/layouts/partials/menupermalink.gotmpl
index 9b6801996e..408235d4c3 100644
--- a/layouts/partials/menupermalink.gotmpl
+++ b/layouts/partials/menupermalink.gotmpl
@@ -6,11 +6,7 @@
       {{- $url = partial "permalink.gotmpl" (dict "to" .) }}
     {{- else }}
       {{- $msg := printf "%q: config menu link '%s' is not a page" $.page.File.Filename .PageRef }}
-      {{- if eq $errorlevel "warning" }}
-        {{- warnf $msg }}
-      {{- else if eq $errorlevel "error" }}
-        {{- errorf $msg }}
-      {{- end }}
+      {{- partial "_relearn/urlErrorReport.gotmpl" (dict "url" .PageRef "page" $.page "param" "link" "msg" $msg) }}
     {{- end }}
   {{- else }}
     {{- with .URL }}
@@ -20,11 +16,7 @@
         {{- partialCached "_relearn/urlExists.gotmpl" (dict "url" $url "page" $.page "type" "menu link") $u.String }}
       {{- else }}
         {{- $msg := printf "%q: config menu link '%s' given by 'URL' is not verified; if it is a page use 'PageRef' instead" $.page.File.Filename . }}
-        {{- if eq $errorlevel "warning" }}
-          {{- warnf $msg }}
-        {{- else if eq $errorlevel "error" }}
-          {{- errorf $msg }}
-        {{- end }}
+        {{- partial "_relearn/urlErrorReport.gotmpl" (dict "url" . "page" $.page "param" "link" "msg" $msg) }}
       {{- end }}
     {{- end }}
   {{- end }}
diff --git a/layouts/partials/meta.html b/layouts/partials/meta.html
index f188829830..edbe8e0606 100644
--- a/layouts/partials/meta.html
+++ b/layouts/partials/meta.html
@@ -21,11 +21,7 @@
             {{- $url = partial "permalink.gotmpl" (dict "to" .) }}
         {{- else }}
             {{- $msg := printf "%q: front matter crosslink '%s' is not a page" .File.Filename .Params.menuPageRef }}
-            {{- if eq $errorlevel "warning" }}
-                {{- warnf $msg }}
-            {{- else if eq $errorlevel "error" }}
-                {{- errorf $msg }}
-            {{- end }}
+            {{- partial "_relearn/urlErrorReport.gotmpl" (dict "url" .Params.menuPageRef "page" . "param" "link" "msg" $msg) }}
         {{- end }}
     {{- else if .Params.menuUrl }}
         {{- $url = .Params.menuUrl }}
@@ -34,11 +30,7 @@
             {{- partialCached "_relearn/urlExists.gotmpl" (dict "url" $url "page" . "type" "menu link") $u.String }}
         {{- else }}
             {{- $msg := printf "%q: front matter crosslink '%s' given by 'menuURL' is not verified; if it is a page use 'menuPageRef' instead" .File.Filename .Params.menuUrl }}
-            {{- if eq $errorlevel "warning" }}
-                {{- warnf $msg }}
-            {{- else if eq $errorlevel "error" }}
-                {{- errorf $msg }}
-            {{- end }}
+            {{- partial "_relearn/urlErrorReport.gotmpl" (dict "url" .Params.menuUrl "page" . "param" "link" "msg" $msg) }}
         {{- end }}
     {{- end }}
     {{- if $url }}
diff --git a/layouts/partials/shortcodes/image.html b/layouts/partials/shortcodes/image.html
index 4245379f10..f60c4f846d 100644
--- a/layouts/partials/shortcodes/image.html
+++ b/layouts/partials/shortcodes/image.html
@@ -34,13 +34,8 @@
       {{- $src = printf "%s#%s" $src . }}
     {{- end }}
   {{- else }}
-    {{- $errorlevel := or $page.Params.image.errorlevel $page.Site.Params.image.errorlevel }}
     {{- $msg := printf "%q: image '%s' is not a resource" $page.File.Filename .url }}
-    {{- if eq $errorlevel "warning" }}
-      {{- warnf $msg }}
-    {{- else if eq $errorlevel "error" }}
-      {{- errorf $msg }}
-    {{- end }}
+    {{- partial "_relearn/urlErrorReport.gotmpl" (dict "url" .url "page" $page "param" "image" "msg" $msg) }}
   {{- end }}
 {{- end }}
 {{- if $u.RawQuery }}
diff --git a/layouts/partials/shortcodes/include.html b/layouts/partials/shortcodes/include.html
index f83525594c..67c929b545 100644
--- a/layouts/partials/shortcodes/include.html
+++ b/layouts/partials/shortcodes/include.html
@@ -17,13 +17,8 @@
   {{- if (fileExists .file) }}
     {{- $content = .file | readFile }}
   {{- else }}
-    {{- $errorlevel := or $page.Params.include.errorlevel $page.Site.Params.include.errorlevel }}
     {{- $msg := printf "%q: include '%s' is not a page, a resource or a file" $page.File.Filename .file }}
-    {{- if eq $errorlevel "warning" }}
-      {{- warnf $msg }}
-    {{- else if eq $errorlevel "error" }}
-      {{- errorf $msg }}
-    {{- end }}
+    {{- partial "_relearn/urlErrorReport.gotmpl" (dict "url" .file "page" $page "param" "include" "msg" $msg) }}
   {{- end }}
 {{- end }}
 {{- $hideFirstHeading := .hidefirstheading | default false }}
diff --git a/layouts/partials/shortcodes/link.html b/layouts/partials/shortcodes/link.html
index e4b65779d7..8b29bef22a 100644
--- a/layouts/partials/shortcodes/link.html
+++ b/layouts/partials/shortcodes/link.html
@@ -75,16 +75,12 @@
         "parsedURL" $u
         "renderHookName" "link"
       }}
-      {{- partial "inline/h-rh-l/validate-fragment.html" $ctx }}
+      {{- partial "inline/validate-fragment.html" $ctx }}
       {{- $href = printf "%s#%s" $href . }}
     {{- end }}
   {{- else }}
     {{- $msg := printf "%q: link '%s' is not a page or a resource" $page.File.Filename .url }}
-    {{- if eq $errorlevel "warning" }}
-      {{- warnf $msg }}
-    {{- else if eq $errorlevel "error" }}
-      {{- errorf $msg }}
-    {{- end }}
+    {{- partial "_relearn/urlErrorReport.gotmpl" (dict "url" .url "page" $page "param" "link" "msg" $msg) }}
   {{- end }}
 {{- end }}
 {{- $attributes = $attributes | merge (dict "href" $href) -}}
@@ -95,7 +91,7 @@
     {{- end }}
   {{- end }}>{{ $content | safeHTML }}</a>
 
-{{- define "partials/inline/h-rh-l/validate-fragment.html" }}
+{{- define "partials/inline/validate-fragment.html" }}
   {{- /*
   Validates the fragment portion of a link destination.
 
diff --git a/layouts/partials/shortcodes/openapi.html b/layouts/partials/shortcodes/openapi.html
index 3d6103081d..2f931a474c 100644
--- a/layouts/partials/shortcodes/openapi.html
+++ b/layouts/partials/shortcodes/openapi.html
@@ -18,13 +18,8 @@
     {{- $src = "" }}
     {{- $spec = .Content }}
   {{- else }}
-    {{- $errorlevel := or $page.Params.openapi.errorlevel $page.Site.Params.openapi.errorlevel }}
     {{- $msg := printf "%q: OpenAPI spec '%s' is not a resource" $page.File.Filename .src }}
-    {{- if eq $errorlevel "warning" }}
-      {{- warnf $msg }}
-    {{- else if eq $errorlevel "error" }}
-      {{- errorf $msg }}
-    {{- end }}
+    {{- partial "_relearn/urlErrorReport.gotmpl" (dict "url" .src "page" $page "param" "openapi" "msg" $msg) }}
   {{- end }}
 {{- end }}
 {{- with $page -}}
diff --git a/layouts/partials/version.txt b/layouts/partials/version.txt
index 47fbcbfe42..9c29833e67 100644
--- a/layouts/partials/version.txt
+++ b/layouts/partials/version.txt
@@ -1 +1 @@
-7.3.2+9527cd17bb1201408284d6b2e99b705ea9bb8a8b
\ No newline at end of file
+7.3.2+239ae4ed64e9976ba7071aa19f4e4f31904742d6
\ No newline at end of file