theme: simplify additional JS dependencies #682

config.toml

@@ -30,3 +30,14 @@
     mediaType = 'text/html'
     permalinkable = false
     noUgly = true
+
+[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"

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

@@ -150,6 +150,40 @@ document.addEventListener( 'themeVariantLoaded', function( e ){
 
 If you are not happy with the shipped variants you can either copy and rename one of the shipped files from `themes/hugo-theme-relearn/static/css` to `static/css`, edit them afterwards to your liking in a text editor and configure the `themeVariant` parameter in your `config.toml` or just use the [interactive variant generator]({{%relref "basics/generator" %}}).
 
-### Output Formats
+## 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. To provide this behavior to the user and extending it for his own shortcodes this can be configured.
+
+Say you want to add a shortcode `myshortcode` that also requires the `jquery` JavaScript library.
+
+1. Write the shortcode file `layouts/partials/shortcode/myshortcode.html` and add the following line
+
+    ````go
+   {{- .Store.Set "hasMyShortcode" true }}
+    ````
+
+1. Add the following snippet to your `config.toml`
+
+    ````go
+    [params.relearn.dependencies]
+      [params.relearn.dependencies.myshortcode]
+        name = "MyShortcode"
+        location = "footer"
+    ````
+
+1. Add the dependency loader file `layouts/dependencies/myshortcode.html`. The loader file will be appended to your header or footer, dependend on the `location` setting in your `config.toml`.
+
+    ````html
+    <script src="https://www.unpkg.com/jquery/dist/jquery.js"></script>
+    ````
+
+Character casing is relevant!
+
+- the `name` setting in your `config.toml` must match the key you used for the store in your `layouts/partials/shortcode/myshortcode.html`.
+- the key on `params.relearn.dependencies` in your `config.toml` must match the file name of your loader file.
+
+See the `math`, `mermaid` and `openapi` shortcodes for examples.
+
+## 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 `config.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

@@ -24,6 +24,8 @@ This document shows you what's new in the latest release. For a detailed list of
 
 - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} It is now possible to adjust the menu width for your whole site. [See the docs]({{% relref "basics/customization#change-the-menu-width" %}}).
 
+- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The theme now provides a mechanism to load further JavaScript dependencies defined by you. This comes in handy if you want to add your own shortcodes that require additional JavaScript code to be loaded. [See the docs]({{% relref "basics/customization#own-shortcodes-with-javascript-dependencies" %}}).
+
 ---
 
 ## 5.22.0 (2023-10-02) {#5220}

exampleSite/layouts/partials/shortcodes/piratify.html

@@ -133,9 +133,10 @@
 	{{- end }}
 	{{- $c = replaceRE (printf "(src|href)=\"([^\"]*?)/%s/([^\"]*?.files/[^\"]*?\")" $langtrg) "${1}=\"${2}/${3}" $c }}
 	{{- if $srcPage }}
-		{{- $page.Store.Set "hasMathJax" (or ($page.Store.Get "hasMathJax") ($srcPage.Store.Get "hasMathJax")) }}
+		{{- range $page.Site.Params.relearn.dependencies }}
-		{{- $page.Store.Set "hasMermaid" (or ($page.Store.Get "hasMermaid") ($srcPage.Store.Get "hasMermaid")) }}
+			{{- $has := printf "has%s" .name }}
-		{{- $page.Store.Set "hasOpenapi" (or ($page.Store.Get "hasOpenapi") ($srcPage.Store.Get "hasOpenapi")) }}
+			{{- $page.Store.Set $has (or ($page.Store.Get $has) ($srcPage.Store.Get $has)) }}
+		{{- end }}
 	{{- end }}
 {{- end }}
 {{ $c | safeHTML }}

layouts/partials/dependencies.html

@@ -0,0 +1,12 @@
+{{- $page := .page }}
+{{- $location := .location }}
+{{- $outputFormat := .outputFormat }}
+{{- 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) }}
+		{{- $dep := printf "dependencies/%s.html" $k }}
+		{{- partial $dep (dict "page" $page) }}
+	{{- end }}
+{{- end }}

layouts/partials/dependencies/mathjax.html

@@ -0,0 +1,45 @@
+{{- $page := .page }}
+{{- with $page }}
+  {{- if isset .Params "mathjaxinitialize" }}
+    {{- $.Scratch.Set "mathJaxInitialize" .Params.mathJaxInitialize }}
+  {{- else if isset .Site.Params "mathjaxinitialize" }}
+    {{- $.Scratch.Set "mathJaxInitialize" .Site.Params.mathJaxInitialize }}
+  {{- else }}
+    {{- $.Scratch.Set "mathJaxInitialize" "{}" }}
+  {{- end }}
+    <script>
+      function useMathJax( config ){
+        if( !Object.assign ){
+          // We don't support MathJax for IE11 anyways, so bail out early
+          return;
+        }
+        window.MathJax = Object.assign( window.MathJax || {}, {
+          loader: {
+            load: ['[tex]/mhchem']
+          },
+          startup: {
+            elements: [
+              '.math'
+            ]
+          },
+          tex: {
+            inlineMath: [
+              ['$', '$'], // allow for single dollars as we set startup.elements
+              ['\\(', '\\)']
+            ]
+          },
+          options: {
+            enableMenu: false // avoid translation hassle for context menu
+          }
+        }, config );
+      }
+      useMathJax( JSON.parse({{ $.Scratch.Get "mathJaxInitialize" }}) );
+    </script>
+  {{- if isset .Params "custommathjaxurl" }}
+    <script id="MathJax-script" async src="{{ .Params.customMathJaxURL }}"></script>
+  {{- else if isset .Site.Params "custommathjaxurl" }}
+    <script id="MathJax-script" async src="{{ .Site.Params.customMathJaxURL }}"></script>
+  {{- 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 }}

layouts/partials/dependencies/mermaid.html

@@ -0,0 +1,30 @@
+{{- $page := .page }}
+{{- 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>
+    <script src="{{"js/d3/d3-ease.min.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}" defer></script>
+    <script src="{{"js/d3/d3-interpolate.min.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}" defer></script>
+    <script src="{{"js/d3/d3-selection.min.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}" defer></script>
+    <script src="{{"js/d3/d3-timer.min.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}" defer></script>
+    <script src="{{"js/d3/d3-transition.min.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}" defer></script>
+    <script src="{{"js/d3/d3-zoom.min.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}" defer></script>
+    <script src="{{"js/js-yaml.min.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}" defer></script>
+  {{- if isset .Params "custommermaidurl" }}
+    <script src="{{ .Params.customMermaidURL }}" defer></script>
+  {{- else if isset .Site.Params "custommermaidurl" }}
+    <script src="{{ .Site.Params.customMermaidURL }}" defer></script>
+  {{- else }}
+    <script src="{{"js/mermaid.min.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}" defer></script>
+  {{- end }}
+  {{- if isset .Params "mermaidinitialize" }}
+    {{- $.Scratch.Set "mermaidInitialize" .Params.mermaidInitialize }}
+  {{- else if isset .Site.Params "mermaidinitialize" }}
+    {{- $.Scratch.Set "mermaidInitialize" .Site.Params.mermaidInitialize }}
+  {{- else }}
+    {{- $.Scratch.Set "mermaidInitialize" "{}" }}
+  {{- end }}
+    <script>
+      window.themeUseMermaid = JSON.parse({{ $.Scratch.Get "mermaidInitialize" }});
+    </script>
+{{- end }}

layouts/partials/dependencies/openapi.html

@@ -0,0 +1,23 @@
+{{- $page := .page }}
+{{- with $page }}
+  {{- $urlOpenapi := "" }}
+  {{- if isset .Params "customopenapiurl" }}
+    {{- $urlOpenapi = .Params.customOpenapiURL }}
+  {{- else if isset .Site.Params "customopenapiurl" }}
+    {{- $urlOpenapi = .Site.Params.customOpenapiURL }}
+  {{- else }}
+    {{- $urlOpenapi = "js/swagger-ui/swagger-ui-bundle.js" | relURL }}
+    {{- if not .Site.Params.disableAssetsBusting }}
+      {{- $urlOpenapi = printf "%s?%d" $urlOpenapi now.Unix }}
+    {{- end }}
+  {{- end }}
+    <script>window.noZensmooth = true;</script>
+    <script src="{{ $urlOpenapi }}" defer></script>
+  {{- $urlOpenapi := replace $urlOpenapi "swagger-ui-bundle" "swagger-ui-standalone-preset" }}
+    <script src="{{ $urlOpenapi }}" defer></script>
+  {{- $urlOpenapi := replace $urlOpenapi "swagger-ui-standalone-preset" "swagger-ui" }}
+  {{- $urlOpenapi := replace $urlOpenapi ".js" ".css" }}
+    <script>
+      window.themeUseOpenapi = { css: {{ $urlOpenapi }}, assetsBuster: {{ cond (not .Site.Params.disableAssetsBusting) now.Unix 0 }} };
+    </script>
+{{- end }}

layouts/partials/footer.html

@@ -6,105 +6,8 @@
 {{- partial "output-partial.hugo" (dict "base" "menu" "page" . "parameter" . "outputFormat" $outputFormat) }}
     <script src="{{"js/clipboard.min.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}" defer></script>
     <script src="{{"js/perfect-scrollbar.min.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}" defer></script>
-{{- $wantsMathJax := or (.Page.Store.Get "hasMathJax") (and (.Page.Store.Get (printf "%sIsNested" $outputFormat)) (.Page.Store.Get "nestedHasMathJax")) }}
+{{- partial "dependencies.html" (dict "page" . "location" "footer" "outputFormat" $outputFormat) }}
-{{- if $wantsMathJax }}
-  {{- if isset .Params "mathjaxinitialize" }}
-    {{- $.Scratch.Set "mathJaxInitialize" .Params.mathJaxInitialize }}
-  {{- else if isset .Site.Params "mathjaxinitialize" }}
-    {{- $.Scratch.Set "mathJaxInitialize" .Site.Params.mathJaxInitialize }}
-  {{- else }}
-    {{- $.Scratch.Set "mathJaxInitialize" "{}" }}
-  {{- end }}
-    <script>
-      function useMathJax( config ){
-        if( !Object.assign ){
-          // We don't support MathJax for IE11 anyways, so bail out early
-          return;
-        }
-        window.MathJax = Object.assign( window.MathJax || {}, {
-          loader: {
-            load: ['[tex]/mhchem']
-          },
-          startup: {
-            elements: [
-              '.math'
-            ]
-          },
-          tex: {
-            inlineMath: [
-              ['$', '$'], // allow for single dollars as we set startup.elements
-              ['\\(', '\\)']
-            ]
-          },
-          options: {
-            enableMenu: false // avoid translation hassle for context menu
-          }
-        }, config );
-      }
-      useMathJax( JSON.parse({{ $.Scratch.Get "mathJaxInitialize" }}) );
-    </script>
-  {{- if isset .Params "custommathjaxurl" }}
-    <script id="MathJax-script" async src="{{ .Params.customMathJaxURL }}"></script>
-  {{- else if isset .Site.Params "custommathjaxurl" }}
-    <script id="MathJax-script" async src="{{ .Site.Params.customMathJaxURL }}"></script>
-  {{- 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 }}
-{{- $wantsMermaid := or (.Page.Store.Get "hasMermaid") (and (.Page.Store.Get (printf "%sIsNested" $outputFormat)) (.Page.Store.Get "nestedHasMermaid")) }}
-{{- if $wantsMermaid }}
-    <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>
-    <script src="{{"js/d3/d3-ease.min.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}" defer></script>
-    <script src="{{"js/d3/d3-interpolate.min.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}" defer></script>
-    <script src="{{"js/d3/d3-selection.min.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}" defer></script>
-    <script src="{{"js/d3/d3-timer.min.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}" defer></script>
-    <script src="{{"js/d3/d3-transition.min.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}" defer></script>
-    <script src="{{"js/d3/d3-zoom.min.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}" defer></script>
-    <script src="{{"js/js-yaml.min.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}" defer></script>
-  {{- if isset .Params "custommermaidurl" }}
-    <script src="{{ .Params.customMermaidURL }}" defer></script>
-  {{- else if isset .Site.Params "custommermaidurl" }}
-    <script src="{{ .Site.Params.customMermaidURL }}" defer></script>
-  {{- else }}
-    <script src="{{"js/mermaid.min.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}" defer></script>
-  {{- end }}
-  {{- if isset .Params "mermaidinitialize" }}
-    {{- $.Scratch.Set "mermaidInitialize" .Params.mermaidInitialize }}
-  {{- else if isset .Site.Params "mermaidinitialize" }}
-    {{- $.Scratch.Set "mermaidInitialize" .Site.Params.mermaidInitialize }}
-  {{- else }}
-    {{- $.Scratch.Set "mermaidInitialize" "{}" }}
-  {{- end }}
-    <script>
-      window.themeUseMermaid = JSON.parse({{ $.Scratch.Get "mermaidInitialize" }});
-    </script>
-{{- end }}
-{{- $wantsOpenapi := or (.Page.Store.Get "hasOpenapi") (and (.Page.Store.Get (printf "%sIsNested" $outputFormat)) (.Page.Store.Get "nestedHasOpenapi")) }}
-{{- if $wantsOpenapi }}
-  {{- $urlOpenapi := "" }}
-  {{- if isset .Params "customopenapiurl" }}
-    {{- $urlOpenapi = .Params.customOpenapiURL }}
-  {{- else if isset .Site.Params "customopenapiurl" }}
-    {{- $urlOpenapi = .Site.Params.customOpenapiURL }}
-  {{- else }}
-    {{- $urlOpenapi = "js/swagger-ui/swagger-ui-bundle.js" | relURL }}
-    {{- if not .Site.Params.disableAssetsBusting }}
-      {{- $urlOpenapi = printf "%s?%d" $urlOpenapi now.Unix }}
-    {{- end }}
-  {{- end }}
-    <script>window.noZensmooth = true;</script>
-    <script src="{{ $urlOpenapi }}" defer></script>
-  {{- $urlOpenapi := replace $urlOpenapi "swagger-ui-bundle" "swagger-ui-standalone-preset" }}
-    <script src="{{ $urlOpenapi }}" defer></script>
-  {{- $urlOpenapi := replace $urlOpenapi "swagger-ui-standalone-preset" "swagger-ui" }}
-  {{- $urlOpenapi := replace $urlOpenapi ".js" ".css" }}
-    <script>
-      window.themeUseOpenapi = { css: {{ $urlOpenapi }}, assetsBuster: {{ cond (not .Site.Params.disableAssetsBusting) now.Unix 0 }} };
-    </script>
-{{- end }}
     <script src="{{"js/theme.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}" defer></script>
-    {{- partial "custom-footer.html" . }}
+{{- partial "custom-footer.html" . }}
   </body>
 </html>

layouts/partials/nested-article.hugo

@@ -64,8 +64,10 @@
   {{- with .sect }}
     {{- $page := . }}
     {{- partialCached "nested-content.hugo" (dict "page" $page "outputFormat" $outputFormat) $page.RelPermalink "outputFormat" $outputFormat }}
-    {{- $currentNode.Page.Store.Set "nestedHasMathJax" (or ($currentNode.Page.Store.Get "nestedHasMathJax") (.Page.Store.Get "hasMathJax")) }}
+    {{- range $page.Site.Params.relearn.dependencies }}
-    {{- $currentNode.Page.Store.Set "nestedHasMermaid" (or ($currentNode.Page.Store.Get "nestedHasMermaid") (.Page.Store.Get "hasMermaid")) }}
+      {{- $has := printf "has%s" .name }}
-    {{- $currentNode.Page.Store.Set "nestedHasOpenapi" (or ($currentNode.Page.Store.Get "nestedHasOpenapi") (.Page.Store.Get "hasOpenapi")) }}
+      {{- $nestedhas := printf "nestedHas%s" .name }}
+      {{- $currentNode.Page.Store.Set $nestedhas (or ($currentNode.Page.Store.Get $nestedhas) ($page.Page.Store.Get $has)) }}
+      {{- end }}
   {{- end }}
 {{- end }}

layouts/partials/page-meta.hugo

@@ -5,17 +5,13 @@
 {{- $currentNode.Scratch.Delete "relearnIsHiddenNode" }}{{/* the node itself is flagged as hidden */}}
 {{- $currentNode.Scratch.Delete "relearnIsHiddenStem" }}{{/* the node or one of its parents is flagged as hidden */}}
 {{- $currentNode.Scratch.Delete "relearnIsHiddenFrom" }}{{/* the node is hidden from the current page */}}
-{{- $wantsMathjax := or (and (ne $currentNode.Params.disableMathjax nil) (not $currentNode.Params.disableMathjax)) (and (ne .Site.Params.disableMathjax nil) (not .Site.Params.disableMathjax)) }}
+{{- range $currentNode.Site.Params.relearn.dependencies }}
-{{- if $wantsMathjax }}
+	{{- $has := printf "has%s" .name }}
-	{{- $currentNode.Store.Set "hasMathJax" true }}
+	{{- $disable := printf "disable%s" .name }}
-{{- end }}
+	{{- $wants := or (and (ne (index $currentNode.Params $disable) nil) (not (index $currentNode.Params $disable))) (and (ne (index .Site.Params $disable) nil) (not (index .Site.Params $disable))) }}
-{{- $wantsMermaid := or (and (ne $currentNode.Params.disableMermaid nil) (not $currentNode.Params.disableMermaid)) (and (ne .Site.Params.disableMermaid nil) (not .Site.Params.disableMermaid)) }}
+	{{- if $wants }}
-{{- if $wantsMermaid }}
+		{{- $currentNode.Store.Set $has true }}
-	{{- $currentNode.Store.Set "hasMermaid" true }}
+	{{- end }}
-{{- end }}
-{{- $wantsOpenapi := or (and (ne $currentNode.Params.disableOpenapi nil) (not $currentNode.Params.disableOpenapi)) (and (ne .Site.Params.disableOpenapi nil) (not .Site.Params.disableOpenapi)) }}
-{{- if $wantsOpenapi }}
-	{{- $currentNode.Store.Set "hasOpenapi" true }}
 {{- end }}
 {{- template "relearn-structure" dict "node" .Site.Home "currentnode" $currentNode "hiddenstem" false "hiddencurrent" false "defaultOrdersectionsby" (.Site.Params.ordersectionsby | default "weight") }}
 {{- define "relearn-structure" }}

layouts/partials/shortcodes/openapi.html

@@ -18,5 +18,5 @@
     data-openapi-url="{{ $src }}"
   ></div>
 </div>
-{{- .Store.Set "hasOpenapi" true }}
+{{- .Store.Set "hasOpenApi" true }}
 {{- end }}

layouts/partials/stylesheet.html

@@ -30,6 +30,7 @@
     <link href="{{"css/ie.css" | relURL}}{{ if $assetBusting }}?{{ now.Unix }}{{ end }}" rel="stylesheet">
     <script src="{{"js/url.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}"></script>
     <script src="{{"js/variant.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}"></script>
+{{- partial "dependencies.html" (dict "page" . "location" "header" "outputFormat" $outputFormat) }}
     <script>
       {{ "// hack to let hugo tell us how to get to the root when using relativeURLs, it needs to be called *url= for it to do its magic:" | safeJS }}
       {{ "// https://github.com/gohugoio/hugo/blob/145b3fcce35fbac25c7033c91c1b7ae6d1179da8/transform/urlreplacers/absurlreplacer.go#L72" | safeJS }}