diff --git a/exampleSite/content/basics/customization/_index.en.md b/exampleSite/content/basics/customization/_index.en.md index 5693955310..9cefff8a7b 100644 --- a/exampleSite/content/basics/customization/_index.en.md +++ b/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" }} + + {{- 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. diff --git a/exampleSite/content/basics/migration/_index.en.md b/exampleSite/content/basics/migration/_index.en.md index a1f0a82043..ada544268c 100644 --- a/exampleSite/content/basics/migration/_index.en.md +++ b/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. diff --git a/hugo.toml b/hugo.toml index 9886305177..a75ccd4c87 100644 --- a/hugo.toml +++ b/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" diff --git a/layouts/partials/dependencies.html b/layouts/partials/dependencies.html index 66a9b5f671..bede3d732f 100644 --- a/layouts/partials/dependencies.html +++ b/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) }} - {{- $dep := printf "dependencies/%s.html" $k }} - {{- partial $dep (dict "page" $page) }} + {{- 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 "location" $location) }} + {{- end }} {{- end }} {{- end }} \ No newline at end of file diff --git a/layouts/partials/dependencies/mathjax.html b/layouts/partials/dependencies/mathjax.html index 89f5957643..8d53f8aa4a 100644 --- a/layouts/partials/dependencies/mathjax.html +++ b/layouts/partials/dependencies/mathjax.html @@ -1,11 +1,13 @@ {{- $page := .page }} -{{- with $page }} - {{- $init := "{}" }} - {{- if isset .Params "mathjaxinitialize" }} - {{- $init = .Params.mathJaxInitialize }} - {{- else if isset .Site.Params "mathjaxinitialize" }} - {{- $init = .Site.Params.mathJaxInitialize }} - {{- end }} +{{- $location := .location }} +{{- if eq $location "footer" }} + {{- with $page }} + {{- $init := "{}" }} + {{- if isset .Params "mathjaxinitialize" }} + {{- $init = .Params.mathJaxInitialize }} + {{- else if isset .Site.Params "mathjaxinitialize" }} + {{- $init = .Site.Params.mathJaxInitialize }} + {{- end }} - {{- if and (isset .Params "custommathjaxurl") .Params.customMathJaxURL }} + {{- if and (isset .Params "custommathjaxurl") .Params.customMathJaxURL }} - {{- else if and (isset .Site.Params "custommathjaxurl") .Site.Params.customMathJaxURL }} + {{- else if and (isset .Site.Params "custommathjaxurl") .Site.Params.customMathJaxURL }} - {{- else }} + {{- else }} + {{- end }} {{- end }} {{- end }} \ No newline at end of file diff --git a/layouts/partials/dependencies/mermaid.html b/layouts/partials/dependencies/mermaid.html index 435bf870a8..4428481af1 100644 --- a/layouts/partials/dependencies/mermaid.html +++ b/layouts/partials/dependencies/mermaid.html @@ -1,5 +1,7 @@ {{- $page := .page }} -{{- with $page }} +{{- $location := .location }} +{{- if eq $location "footer" }} + {{- with $page }} @@ -10,20 +12,21 @@ - {{- if and (isset .Params "custommermaidurl") .Params.customMermaidURL }} + {{- if and (isset .Params "custommermaidurl") .Params.customMermaidURL }} - {{- else if and (isset .Site.Params "custommermaidurl") .Site.Params.customMermaidURL }} + {{- else if and (isset .Site.Params "custommermaidurl") .Site.Params.customMermaidURL }} - {{- else }} + {{- else }} - {{- end }} - {{- $init := "{}" }} - {{- if isset .Params "mermaidinitialize" }} - {{- $init = .Params.mermaidInitialize }} - {{- else if isset .Site.Params "mermaidinitialize" }} - {{- $init = .Site.Params.mermaidInitialize }} - {{- end }} + {{- end }} + {{- $init := "{}" }} + {{- if isset .Params "mermaidinitialize" }} + {{- $init = .Params.mermaidInitialize }} + {{- else if isset .Site.Params "mermaidinitialize" }} + {{- $init = .Site.Params.mermaidInitialize }} + {{- end }} + {{- end }} {{- end }} \ No newline at end of file diff --git a/layouts/partials/dependencies/openapi.html b/layouts/partials/dependencies/openapi.html index f9f59a8766..73cefc8893 100644 --- a/layouts/partials/dependencies/openapi.html +++ b/layouts/partials/dependencies/openapi.html @@ -1,27 +1,30 @@ {{- $page := .page }} -{{- with $page }} +{{- $location := .location }} +{{- if eq $location "footer" }} + {{- with $page }} - {{- $urlOpenapi := "" }} - {{- $relOpenapi := "" }} - {{- $cssInProject := false }} - {{- if and (isset .Params "customopenapiurl") .Params.customOpenapiURL }} - {{- $urlOpenapi = .Params.customOpenapiURL }} - {{- $relOpenapi = .Params.customOpenapiURL }} - {{- else if and (isset .Site.Params "customopenapiurl") .Site.Params.customOpenapiURL }} - {{- $urlOpenapi = .Site.Params.customOpenapiURL }} - {{- $relOpenapi = .Site.Params.customOpenapiURL }} - {{- else }} - {{- $urlOpenapi = printf "%s%s" ("js/swagger-ui/swagger-ui-bundle.js" | relURL) (cond .Site.Params.disableAssetsBusting "" (printf "?%d" now.Unix)) }} - {{- $relOpenapi = printf "%s%s" ("/js/swagger-ui/swagger-ui-bundle.js") (cond .Site.Params.disableAssetsBusting "" (printf "?%d" now.Unix)) }} - {{- $cssInProject = true }} - {{- end }} + {{- $urlOpenapi := "" }} + {{- $relOpenapi := "" }} + {{- $cssInProject := false }} + {{- if and (isset .Params "customopenapiurl") .Params.customOpenapiURL }} + {{- $urlOpenapi = .Params.customOpenapiURL }} + {{- $relOpenapi = .Params.customOpenapiURL }} + {{- else if and (isset .Site.Params "customopenapiurl") .Site.Params.customOpenapiURL }} + {{- $urlOpenapi = .Site.Params.customOpenapiURL }} + {{- $relOpenapi = .Site.Params.customOpenapiURL }} + {{- else }} + {{- $urlOpenapi = printf "%s%s" ("js/swagger-ui/swagger-ui-bundle.js" | relURL) (cond .Site.Params.disableAssetsBusting "" (printf "?%d" now.Unix)) }} + {{- $relOpenapi = printf "%s%s" ("/js/swagger-ui/swagger-ui-bundle.js") (cond .Site.Params.disableAssetsBusting "" (printf "?%d" now.Unix)) }} + {{- $cssInProject = true }} + {{- end }} - {{- $urlOpenapi := replace $urlOpenapi "swagger-ui-bundle" "swagger-ui-standalone-preset" }} + {{- $urlOpenapi := replace $urlOpenapi "swagger-ui-bundle" "swagger-ui-standalone-preset" }} - {{- $relOpenapi := replace $relOpenapi "swagger-ui-bundle" "swagger-ui" }} - {{- $relOpenapi := replace $relOpenapi ".js" ".css" }} + {{- $relOpenapi := replace $relOpenapi "swagger-ui-bundle" "swagger-ui" }} + {{- $relOpenapi := replace $relOpenapi ".js" ".css" }} + {{- end }} {{- end }} \ No newline at end of file