diff --git a/config.toml b/config.toml index 72e6c292d2..25f1f43e69 100644 --- a/config.toml +++ b/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" diff --git a/exampleSite/content/basics/customization/_index.en.md b/exampleSite/content/basics/customization/_index.en.md index 7340b0428d..64b5165f30 100644 --- a/exampleSite/content/basics/customization/_index.en.md +++ b/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 + + ```` + +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. diff --git a/exampleSite/content/basics/migration/_index.en.md b/exampleSite/content/basics/migration/_index.en.md index 1e3c777870..bcd1a33035 100644 --- a/exampleSite/content/basics/migration/_index.en.md +++ b/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} diff --git a/exampleSite/layouts/partials/shortcodes/piratify.html b/exampleSite/layouts/partials/shortcodes/piratify.html index 1809834f0a..90c314e302 100644 --- a/exampleSite/layouts/partials/shortcodes/piratify.html +++ b/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")) }} - {{- $page.Store.Set "hasMermaid" (or ($page.Store.Get "hasMermaid") ($srcPage.Store.Get "hasMermaid")) }} - {{- $page.Store.Set "hasOpenapi" (or ($page.Store.Get "hasOpenapi") ($srcPage.Store.Get "hasOpenapi")) }} + {{- range $page.Site.Params.relearn.dependencies }} + {{- $has := printf "has%s" .name }} + {{- $page.Store.Set $has (or ($page.Store.Get $has) ($srcPage.Store.Get $has)) }} + {{- end }} {{- end }} {{- end }} {{ $c | safeHTML }} \ No newline at end of file diff --git a/layouts/partials/dependencies.html b/layouts/partials/dependencies.html new file mode 100644 index 0000000000..66a9b5f671 --- /dev/null +++ b/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 }} \ No newline at end of file diff --git a/layouts/partials/dependencies/mathjax.html b/layouts/partials/dependencies/mathjax.html new file mode 100644 index 0000000000..ae45a6a182 --- /dev/null +++ b/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 }} + + {{- if isset .Params "custommathjaxurl" }} + + {{- else if isset .Site.Params "custommathjaxurl" }} + + {{- else }} + + {{- end }} +{{- end }} \ No newline at end of file diff --git a/layouts/partials/dependencies/mermaid.html b/layouts/partials/dependencies/mermaid.html new file mode 100644 index 0000000000..52567acbb6 --- /dev/null +++ b/layouts/partials/dependencies/mermaid.html @@ -0,0 +1,30 @@ +{{- $page := .page }} +{{- with $page }} + + + + + + + + + + + {{- if isset .Params "custommermaidurl" }} + + {{- else if isset .Site.Params "custommermaidurl" }} + + {{- else }} + + {{- 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 }} + +{{- end }} \ No newline at end of file diff --git a/layouts/partials/dependencies/openapi.html b/layouts/partials/dependencies/openapi.html new file mode 100644 index 0000000000..18dd29bd3a --- /dev/null +++ b/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 }} + + + {{- $urlOpenapi := replace $urlOpenapi "swagger-ui-bundle" "swagger-ui-standalone-preset" }} + + {{- $urlOpenapi := replace $urlOpenapi "swagger-ui-standalone-preset" "swagger-ui" }} + {{- $urlOpenapi := replace $urlOpenapi ".js" ".css" }} + +{{- end }} \ No newline at end of file diff --git a/layouts/partials/footer.html b/layouts/partials/footer.html index 1c1f88f26f..4b70bc2d78 100644 --- a/layouts/partials/footer.html +++ b/layouts/partials/footer.html @@ -6,105 +6,8 @@ {{- partial "output-partial.hugo" (dict "base" "menu" "page" . "parameter" . "outputFormat" $outputFormat) }} -{{- $wantsMathJax := or (.Page.Store.Get "hasMathJax") (and (.Page.Store.Get (printf "%sIsNested" $outputFormat)) (.Page.Store.Get "nestedHasMathJax")) }} -{{- 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 }} - - {{- if isset .Params "custommathjaxurl" }} - - {{- else if isset .Site.Params "custommathjaxurl" }} - - {{- else }} - - {{- end }} -{{- end }} -{{- $wantsMermaid := or (.Page.Store.Get "hasMermaid") (and (.Page.Store.Get (printf "%sIsNested" $outputFormat)) (.Page.Store.Get "nestedHasMermaid")) }} -{{- if $wantsMermaid }} - - - - - - - - - - - {{- if isset .Params "custommermaidurl" }} - - {{- else if isset .Site.Params "custommermaidurl" }} - - {{- else }} - - {{- 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 }} - -{{- 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 }} - - - {{- $urlOpenapi := replace $urlOpenapi "swagger-ui-bundle" "swagger-ui-standalone-preset" }} - - {{- $urlOpenapi := replace $urlOpenapi "swagger-ui-standalone-preset" "swagger-ui" }} - {{- $urlOpenapi := replace $urlOpenapi ".js" ".css" }} - -{{- end }} +{{- partial "dependencies.html" (dict "page" . "location" "footer" "outputFormat" $outputFormat) }} - {{- partial "custom-footer.html" . }} +{{- partial "custom-footer.html" . }} diff --git a/layouts/partials/nested-article.hugo b/layouts/partials/nested-article.hugo index d9854b92c8..07cbe64f85 100644 --- a/layouts/partials/nested-article.hugo +++ b/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")) }} - {{- $currentNode.Page.Store.Set "nestedHasMermaid" (or ($currentNode.Page.Store.Get "nestedHasMermaid") (.Page.Store.Get "hasMermaid")) }} - {{- $currentNode.Page.Store.Set "nestedHasOpenapi" (or ($currentNode.Page.Store.Get "nestedHasOpenapi") (.Page.Store.Get "hasOpenapi")) }} + {{- range $page.Site.Params.relearn.dependencies }} + {{- $has := printf "has%s" .name }} + {{- $nestedhas := printf "nestedHas%s" .name }} + {{- $currentNode.Page.Store.Set $nestedhas (or ($currentNode.Page.Store.Get $nestedhas) ($page.Page.Store.Get $has)) }} + {{- end }} {{- end }} {{- end }} diff --git a/layouts/partials/page-meta.hugo b/layouts/partials/page-meta.hugo index eca3efe9ea..e570ccc246 100644 --- a/layouts/partials/page-meta.hugo +++ b/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)) }} -{{- if $wantsMathjax }} - {{- $currentNode.Store.Set "hasMathJax" true }} -{{- end }} -{{- $wantsMermaid := or (and (ne $currentNode.Params.disableMermaid nil) (not $currentNode.Params.disableMermaid)) (and (ne .Site.Params.disableMermaid nil) (not .Site.Params.disableMermaid)) }} -{{- if $wantsMermaid }} - {{- $currentNode.Store.Set "hasMermaid" true }} -{{- 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 }} +{{- range $currentNode.Site.Params.relearn.dependencies }} + {{- $has := printf "has%s" .name }} + {{- $disable := printf "disable%s" .name }} + {{- $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))) }} + {{- if $wants }} + {{- $currentNode.Store.Set $has true }} + {{- end }} {{- end }} {{- template "relearn-structure" dict "node" .Site.Home "currentnode" $currentNode "hiddenstem" false "hiddencurrent" false "defaultOrdersectionsby" (.Site.Params.ordersectionsby | default "weight") }} {{- define "relearn-structure" }} diff --git a/layouts/partials/shortcodes/openapi.html b/layouts/partials/shortcodes/openapi.html index 2b84b8342a..4a1ee0fb6d 100644 --- a/layouts/partials/shortcodes/openapi.html +++ b/layouts/partials/shortcodes/openapi.html @@ -18,5 +18,5 @@ data-openapi-url="{{ $src }}" > -{{- .Store.Set "hasOpenapi" true }} +{{- .Store.Set "hasOpenApi" true }} {{- end }} \ No newline at end of file diff --git a/layouts/partials/stylesheet.html b/layouts/partials/stylesheet.html index d908a7beac..e244b62e9f 100644 --- a/layouts/partials/stylesheet.html +++ b/layouts/partials/stylesheet.html @@ -30,6 +30,7 @@ +{{- partial "dependencies.html" (dict "page" . "location" "header" "outputFormat" $outputFormat) }}