dependencies: make loader more versatile #820

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

@@ -174,13 +174,13 @@ If you are unhappy with the default, you can define the following CSS variable i
 
 ## Own Shortcodes with JavaScript Dependencies
 
-Certain shortcodes make use of additional JavaScript files. The theme only loads these dependencies if the shortcode is used. To do so correctly the theme adds management code in various files.
+Certain shortcodes make use of additional dependencies like JavaScript and CSS files. The theme only loads these dependencies if the shortcode is used. To do so correctly the theme adds management code in various files.
 
 You can you use this mechanism in your own shortcodes. Say you want to add a shortcode `myshortcode` that also requires the `jquery` JavaScript library.
 
 1. Write the shortcode file `layouts/shortcodes/myshortcode.html` and add the following line
 
-    ````go
+    ````go {title="layouts/shortcodes/myshortcode.html"}
    {{- .Page.Store.Set "hasMyShortcode" true }}
     ````
 
@@ -190,13 +190,17 @@ You can you use this mechanism in your own shortcodes. Say you want to add a sho
     [params.relearn.dependencies]
       [params.relearn.dependencies.myshortcode]
         name = "MyShortcode"
-        location = "footer"
     {{< /multiconfig >}}
 
-1. Add the dependency loader file `layouts/partials/dependencies/myshortcode.html`. The loader file will be appended to your header or footer, dependend on the `location` setting in your `hugo.toml`.
+1. Add the dependency loader file `layouts/partials/dependencies/myshortcode.html`. The loader file will be called from multiple locations inside of the theme with the parameter `page` containing the current [page](https://gohugo.io/methods/page/) variable and `location` with one of the currently defined locations
 
-    ````html
+    * `header`: if called at the end of the HTML `head` element
+    * `footer`: if called at the end of the HTML `body` element
+
+    ````go {title="layouts/partials/dependencies/myshortcode.html"}
+    {{- if eq .location "footer" }}
       <script src="https://www.unpkg.com/jquery/dist/jquery.js"></script>
+    {{- end }}
     ````
 
 Character casing is relevant!
@@ -206,6 +210,15 @@ Character casing is relevant!
 
 See the `math`, `mermaid` and `openapi` shortcodes for examples.
 
+{{% notice note %}}
+If you are really into customization of the theme and want to use the dependency loader for your own locations, you can do this by simply calling it from inside of your overriden partials
+
+````go
+{{- partial "dependencies.html" (dict "page" . "location" "mylocation") }}
+````
+
+{{% /notice %}}
+
 ## Output Formats
 
 Certain parts of the theme can be changed for support of your own [output formats](https://gohugo.io/templates/output-formats/). Eg. if you define a new output format `PLAINTEXT` in your `hugo.toml`, you can add a file `layouts/partials/header.plaintext.html` to change the way, the page header should look like for that output format.

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

@@ -20,6 +20,14 @@ 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="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.
+
+  With the new mechanism, your dependency loader now receives an additional `location` parameter instead that you can query to inject your dependencies in the desired location.
+
+  By that you can now call the dependency mechanism in your own overriden partials by giving it a distinct `location` parameter. In addition your injected files can now be spread to multiple locations which wasn't previously possible.
+
 - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} You now can scroll forward and backward thru all headings of a page by using `ALT + 🡑` and `ALT + 🡓`. This also works for the `PRINT` output format
 
 - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The breadcrumbs used in the topbar, search results and the taxonomy term lists are now using the pages frontmatter `linktitle` instead of `title` if set.

hugo.toml

@@ -34,10 +34,7 @@
 [params.relearn.dependencies]
   [params.relearn.dependencies.mathjax]
     name = "MathJax"
-    location = "footer"
   [params.relearn.dependencies.mermaid]
     name = "Mermaid"
-    location = "footer"
   [params.relearn.dependencies.openapi]
     name = "OpenApi"
-    location = "footer"

layouts/partials/dependencies.html

@@ -1,12 +1,17 @@
 {{- $page := .page }}
 {{- $location := .location }}
-{{- $outputFormat := .outputFormat }}
+{{- $outputFormat := .outputFormat | default (partial "output-format.hugo" $page) }}
 {{- range $k, $v := $page.Site.Params.relearn.dependencies }}
 	{{- $has := printf "has%s" $v.name }}
 	{{- $nestedhas := printf "nestedHas%s" $v.name }}
     {{- $wants := or ($page.Page.Store.Get $has) (and ($page.Page.Store.Get (printf "%sIsNested" $outputFormat)) ($page.Page.Store.Get $nestedhas)) }}
-	{{- if and $wants (eq $location $v.location) }}
+	{{- if and $wants }}
+		{{- if $v.location }}
+			{{- warnf "DEPRECATED parameter 'location' for dependency '%s' configured in your hugo.toml, query the 'location' parameter inside your dependency loader instead; see https://mcshelby.github.io/hugo-theme-relearn/basics/migration#5270" $k}}
+		{{- end }}
+		{{- if or (not $v.location) (eq $location $v.location) }}
 			{{- $dep := printf "dependencies/%s.html" $k }}
-		{{- partial $dep (dict "page" $page) }}
+			{{- partial $dep (dict "page" $page "location" $location) }}
+		{{- end }}
 	{{- end }}
 {{- end }}

layouts/partials/dependencies/mathjax.html

@@ -1,5 +1,7 @@
 {{- $page := .page }}
-{{- with $page }}
+{{- $location := .location }}
+{{- if eq $location "footer" }}
+  {{- with $page }}
     {{- $init := "{}" }}
     {{- if isset .Params "mathjaxinitialize" }}
       {{- $init = .Params.mathJaxInitialize }}
@@ -41,4 +43,5 @@
     {{- else }}
     <script id="MathJax-script" async src="{{"js/mathjax/tex-mml-chtml.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}"></script>
     {{- end }}
+  {{- end }}
 {{- end }}

layouts/partials/dependencies/mermaid.html

@@ -1,5 +1,7 @@
 {{- $page := .page }}
-{{- with $page }}
+{{- $location := .location }}
+{{- if eq $location "footer" }}
+  {{- with $page }}
     <script src="{{"js/d3/d3-color.min.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}" defer></script>
     <script src="{{"js/d3/d3-dispatch.min.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}" defer></script>
     <script src="{{"js/d3/d3-drag.min.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}" defer></script>
@@ -26,4 +28,5 @@
     <script>
       window.themeUseMermaid = JSON.parse({{ $init }});
     </script>
+  {{- end }}
 {{- end }}

layouts/partials/dependencies/openapi.html

@@ -1,5 +1,7 @@
 {{- $page := .page }}
-{{- with $page }}
+{{- $location := .location }}
+{{- if eq $location "footer" }}
+  {{- with $page }}
     <script src="{{"js/js-yaml.min.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}" defer></script>
     {{- $urlOpenapi := "" }}
     {{- $relOpenapi := "" }}
@@ -24,4 +26,5 @@
     <script>
       window.themeUseOpenapi = { css: {{ $relOpenapi }}, cssInProject: {{ $cssInProject | safeJS }}, assetsBuster: {{ cond (not .Site.Params.disableAssetsBusting) now.Unix 0 }} };
     </script>
+  {{- end }}
 {{- end }}