openapi: adjust to Hugo's build-in link render hook #860

- resolve render hook destination with leading ./
- configurable message for unresolved local adresses

exampleSite/config/_default/params.toml

@@ -448,3 +448,13 @@ disableOpenapi = true
 # version will be used.
 # This can be overridden in the page's frontmatter.
 customOpenapiURL = "" # "https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"
+
+# What to do when a local OpenAPI spec link is not resolved.
+# Default: ""
+# You can control what should happen if a local OpenAPI spec link can not be resolved
+# to a resource. If not set, the unresolved link is written as given into the resulting
+# output. If set to `warning` the same happens and an additional warning is
+# printed. If set to `error` an error message is printed and the build is
+# aborted.
+# Please note that this can not resolve files inside of your `static` directory.
+openapi.errorlevel = "error"

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

@@ -22,6 +22,8 @@ This document shows you what's new in the latest release and flags it with one o
 
 - {{% badge style="note" title=" " %}}Change{{% /badge %}} The [`include` shortcode](shortcodes/include) is now able to resolve links to pages as well as resources or files in the file system (the old behavior).
 
+- {{% 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.
+
 ---
 
 ## 6.0.0 (2024-04-27) {#600}

exampleSite/content/shortcodes/openapi/_index.en.md

@@ -33,7 +33,7 @@ While the examples are using shortcodes with named parameter you are free to als
 
 | Name                 | Default          | Notes       |
 |----------------------|------------------|-------------|
-| **src**              | _<empty>_  | The URL to the OpenAPI specification file. This can be relative to the URL of your page if it is a leaf or branch bundle. |
+| **src**              | _<empty>_  | The path to the to the OpenAPI specification resource or URL to be used. Resource paths adhere to [Hugo's logical path](https://gohugo.io/methods/page/path/). |
 
 {{% notice note %}}
 If you want to print out (or generate a PDF) from your OpenAPI documentation, don't initiate printing directly from the page because the elements are optimized for interactive usage in a browser.

layouts/partials/shortcodes/openapi.html

@@ -3,16 +3,27 @@
   {{- $page = .context }}
   {{- warnf "%q: DEPRECATED parameter 'context' for shortcode 'openapi' found, use 'page' instead; see https://mcshelby.github.io/hugo-theme-relearn/basics/migration#5180" $page.File.Filename }}
 {{- end }}
-{{- $src := .src }}
+{{- $u := urls.Parse .src }}
+{{- $src := $u.String }}
 {{- $spec := "" }}
 {{- $id := cond (or (eq .id nil) (eq .id "")) (partial "make-random-md5.hugo" $page) .id }}
-{{- with $page }}
-{{- with or
-  (.Resources.Get $src)
-  (resources.Get $src)
-}}
-  {{- $spec = .Content }}
+{{- if not $u.IsAbs }}
+  {{- $path := strings.TrimPrefix "./" $u.Path }}
+  {{- with or
+    ($page.Resources.Get $path)
+    (resources.Get $path)
+  }}
+    {{- $src = "" }}
+    {{- $spec = .Content }}
+  {{- else }}
+    {{- if eq $page.Site.Params.openapi.errorlevel "warning" }}
+      {{- warnf "%q: OpenAPI spec link '%s' is not a resource but linked anyways" $page.File.Filename .url }}
+    {{- else if eq $page.Site.Params.openapi.errorlevel "error" }}
+      {{- errorf "%q: OpenAPI spec link '%s' is not a resource" $page.File.Filename .url }}
+    {{- end }}
+  {{- end }}
 {{- end }}
+{{- with $page }}
 <div class="sc-openapi-wrapper is-loading helper-loading-container">
   <div
     class="sc-openapi-container"