math: adhere to Hugo's default config params #923

exampleSite/config/_default/params.toml

@@ -443,16 +443,16 @@ disableExplicitIndexURLs = false
 # This can be overridden in the page's frontmatter.
 mathJaxInitialize = "{}"
 
-# Only load MathJax if needed.
-# Default: true
-# If a Math shortcode is found, the option will be ignored and
-# MathJax will be loaded regardlessly. The option is still useful in case you
-# are using scripting to set up your graph. In this case no shortcode or
-# Markdown codefence is involved and the library is not loaded by default. In this case
-# you can set `disableMathJax=false` in your frontmatter to force the library to
-# be loaded.
+# Force load Math on every page.
+# Default: false
+# If a, Math shortcode or codefence is found, the option will be ignored and
+# Math will be loaded regardlessly. This option is useful in case you
+# are using passthrough configuration to render your math. In this case no shortcode or
+# codefence is involved and the library is not loaded by default so you can
+# force loading it by setting `math=true`.
+# This option has an alias `math.force`.
 # This can be overridden in the page's frontmatter.
-disableMathJax = true
+math = false
 
 # URL for external MathJax library.
 # Default: not set
@@ -479,16 +479,15 @@ mermaidZoom = true
 # This can be overridden in the page's frontmatter.
 mermaidInitialize = "{ \"securityLevel\": \"loose\" }"
 
-# Only load Mermaid if needed.
-# Default: true
-# If a Mermaid shortcode or Markdown codefence is found, the option will be ignored and
-# Mermaid will be loaded regardlessly. The option is still useful in case you
-# are using scripting to set up your graph. In this case no shortcode or
-# Markdown codefence is involved and the library is not loaded by default. In this case
-# you can set `disableMermaid=false` in your frontmatter to force the library to
-# be loaded.
+# Force load Mermaid on every page.
+# Default: false
+# If a Mermaid shortcode or codefence is found, the option will be ignored and
+# Mermaid will be loaded regardlessly. This option is useful in case you
+# are using scripting to render your graph. In this case no shortcode or
+# codefence is involved and the library is not loaded by default so you can
+# force loading it by setting `mermaid.force=true`.
 # This can be overridden in the page's frontmatter.
-disableMermaid = true
+mermaid.force = false
 
 # URL for external Mermaid library.
 # Default: not set
@@ -501,16 +500,15 @@ customMermaidURL = "" # "https://unpkg.com/mermaid/dist/mermaid.min.js"
 # OpenApi
 # These options configure how OpenAPI specifications are displayed.
 
-# Only load OpenAPI if needed.
-# Default: true
-# If a OpenAPI shortcode is found, the option will be ignored and
-# OpenAPI will be loaded regardlessly. The option is still useful in case you
-# are using scripting to set up your graph. In this case no shortcode or
-# Markdown codefence is involved and the library is not loaded by default. In this case
-# you can set `disableOpenapi=false` in your frontmatter to force the library to
-# be loaded.
+# Force load OpenAPI on every page.
+# Default: false
+# If a, OpenAPI shortcode or codefence is found, the option will be ignored and
+# OpenAPI will be loaded regardlessly. This option is useful in case you
+# are using scripting to render your spec. In this case no shortcode or
+# codefence is involved and the library is not loaded by default so you can
+# force loading it by setting `openapi.force=true`.
 # This can be overridden in the page's frontmatter.
-disableOpenapi = true
+oppenapi.force = false
 
 # URL for external OpenAPI library.
 # Default: not set

exampleSite/content/configuration/appearance/generator/_index.en.md

@@ -1,6 +1,6 @@
 +++
 description = "An interactive tool to generate color variant stylesheets"
-disableMermaid = false
+mermaid.force = true
 options = ["themeVariant"]
 title = "Stylesheet Generator"
 weight = 9

exampleSite/content/content/frontmatter/frontmatter.toml

@@ -226,16 +226,16 @@ link.errorlevel = ""
 # If not set, the set value of your site's hugo.toml is used.
 mathJaxInitialize = "{}"
 
-# Only load MathJax if needed.
-# Default: true
-# If a Math shortcode is found, the option will be ignored and
-# MathJax will be loaded regardlessly. The option is still useful in case you
-# are using scripting to set up your graph. In this case no shortcode or
-# Markdown codefence is involved and the library is not loaded by default. In this case
-# you can set `disableMathJax=false` in your frontmatter to force the library to
-# be loaded.
+# Force load Math on every page.
+# Default: false
+# If a, Math shortcode or codefence is found, the option will be ignored and
+# Math will be loaded regardlessly. This option is useful in case you
+# are using passthrough configuration to render your math. In this case no shortcode or
+# codefence is involved and the library is not loaded by default so you can
+# force loading it by setting `math=true`.
+# This option has an alias `math.force`.
 # If not set, the set value of your site's hugo.toml is used.
-disableMathJax = true
+math = false
 
 # URL for external MathJax library.
 # Default: not set
@@ -262,16 +262,15 @@ mermaidZoom = true
 # If not set, the set value of your site's hugo.toml is used.
 mermaidInitialize = "{ \"securityLevel\": \"loose\" }"
 
-# Only load Mermaid if needed.
-# Default: true
-# If a Mermaid shortcode or Markdown codefence is found, the option will be ignored and
-# Mermaid will be loaded regardlessly. The option is still useful in case you
-# are using scripting to set up your graph. In this case no shortcode or
-# Markdown codefence is involved and the library is not loaded by default. In this case
-# you can set `disableMermaid=false` in your frontmatter to force the library to
-# be loaded.
+# Force load Mermaid on every page.
+# Default: false
+# If a Mermaid shortcode or codefence is found, the option will be ignored and
+# Mermaid will be loaded regardlessly. This option is useful in case you
+# are using scripting to render your graph. In this case no shortcode or
+# codefence is involved and the library is not loaded by default so you can
+# force loading it by setting `mermaid.force=true`.
 # If not set, the set value of your site's hugo.toml is used.
-disableMermaid = true
+mermaid.force = false
 
 # URL for external Mermaid library.
 # Default: not set
@@ -284,16 +283,15 @@ customMermaidURL = "" # "https://unpkg.com/mermaid/dist/mermaid.min.js"
 # OpenApi
 # These options configure how OpenAPI specifications are displayed.
 
-# Only load OpenAPI if needed.
-# Default: true
-# If a OpenAPI shortcode is found, the option will be ignored and
-# OpenAPI will be loaded regardlessly. The option is still useful in case you
-# are using scripting to set up your graph. In this case no shortcode or
-# Markdown codefence is involved and the library is not loaded by default. In this case
-# you can set `disableOpenapi=false` in your frontmatter to force the library to
-# be loaded.
+# Load OpenAPI on every page.
+# Default: false
+# If a, OpenAPI shortcode or codefence is found, the option will be ignored and
+# OpenAPI will be loaded regardlessly. This option is useful in case you
+# are using scripting to render your spec. In this case no shortcode or
+# codefence is involved and the library is not loaded by default so you can
+# force loading it by setting `openapi.force=true`.
 # If not set, the set value of your site's hugo.toml is used.
-disableOpenapi = true
+oppenapi.force = false
 
 # URL for external OpenAPI library.
 # Default: not set

exampleSite/content/introduction/releasenotes/7/0.en.md

@@ -65,6 +65,12 @@ weight = -0
 
   `--MAIN-TITLES-TEXT-font` was renamed to `--MAIN-TITLES-font`, `--MAIN-TITLES-H<n>-color` was renamed to `--MAIN-TITLES-H<n>-TEXT-color`.
 
+- {{% badge style="note" title=" " %}}Change{{% /badge %}} The options and front matter to force loading a [math](shortcodes/math#force-loading-of-the-mathjax-library), [mermaid](shortcodes/mermaid#force-loading-of-the-mermaid-library) or [openapi](shortcodes/openapi#force-loading-of-the-swagger-ui-library) library has been changed.
+
+  Previously you had to set the unintuitive `disableMathJax=false` to force load the math library in case of a passthrough configuration. This is replaced by the simpler `math=true` or `math.force=true` and is now in line with [Hugo's official documentation](https://gohugo.io/content-management/mathematics/#step-1).
+
+  You don't need to change anything yet but will receive warnings if the old settings are used.
+
 ## New
 
 - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The docs received a much needed overhaul for all chapters besides [Shortcodes](shortcodes/).

exampleSite/content/shortcodes/math.en.md

@@ -1,7 +1,7 @@
 +++
 description = "Beautiful math and chemical formulae"
-frontmatter = ["customMathJaxURL", "disableMathJax", "mathJaxInitialize"]
-options = ["customMathJaxURL", "disableMathJax", "mathJaxInitialize"]
+frontmatter = ["customMathJaxURL", "math", "math.force", "mathJaxInitialize"]
+options = ["customMathJaxURL", "math", "math.force", "mathJaxInitialize"]
 title = "Math"
 +++
 
@@ -95,9 +95,11 @@ customMathJaxURL = "https://unpkg.com/mathjax/es5/tex-mml-chtml.js"
 
 ### Force Loading of the MathJax Library
 
-{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} The MathJax library will be loaded if the page contains math.
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} The MathJax library will be loaded if the page contains a `math` shortcode or codefence.
 
-You can force loading the MathJax library if math wasn't found by setting `disableMathJax=false`. If math was found, the option will be ignored. This comes handy in case you are using [passthrough configuration](#passthrough-configuration) or scripting for creating math.
+You can force loading the MathJax library if no shortcode or codefence was used by setting `math=true`. If a shortcode or codefence was found, the option has no effect. This must be set in case you are using the [passthrough configuration](#passthrough-configuration) to render math.
+
+Instead of `math=true` you can also use the alias `math.force=true`.
 
 ### Passthrough Configuration
 
@@ -117,7 +119,7 @@ You can force loading the MathJax library if math wasn't found by setting `disab
 In this case you have to [force load](#force-loading-of-the-mathjax-library) the MathJax library either in your `hugo.toml` or in your page's front matter as the theme doesn't know if math is used.
 
 {{< multiconfig fm=true >}}
-disableMathJax = false
+math = true
 {{< /multiconfig >}}
 
 [See the example](#passthrough-block-math) on how a passthrough configurations makes using math really easy.
@@ -130,7 +132,7 @@ With passthrough configuration you can just drop your math without enclosing it
 
 This is only available if you are using the [passthrough configuration](#passthrough-configuration).
 
-Just don't forget to [force load](#force-loading-of-the-mathjax-library) the MathJax library by setting `disableMathJax=false` either in your `hugo.toml` or in your page's front matter.
+Just don't forget to [force load](#force-loading-of-the-mathjax-library) the MathJax library by setting `math=true` either in your `hugo.toml` or in your page's front matter.
 
 In passthrough default configuration, block math is generated if you use two consecutive `$$` as a delimiter around your formulae.
 

exampleSite/content/shortcodes/mermaid.en.md

@@ -1,7 +1,7 @@
 +++
 description = "Generate diagrams and flowcharts from text"
-frontmatter = ["customMermaidURL", "disableMermaid", "mermaidInitialize", "mermaidZoom"]
-options = ["customMermaidURL", "disableMermaid", "mermaidInitialize", "mermaidZoom"]
+frontmatter = ["customMermaidURL", "mermaid.force", "mermaidInitialize", "mermaidZoom"]
+options = ["customMermaidURL", "mermaid.force", "mermaidInitialize", "mermaidZoom"]
 title = "Mermaid"
 +++
 
@@ -98,9 +98,9 @@ customMermaidURL = "https://unpkg.com/mermaid/dist/mermaid.min.js"
 
 ### Force Loading of the Mermaid Library
 
-{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} The Mermaid library will be loaded if the page contains a graph.
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} The Mermaid library will be loaded if the page contains an `mermaid` shortcode or codefence.
 
-You can force loading the Mermaid library if a graph wasn't found by setting `disableMermaid=false`. If a graph was found, the option will be ignored. This comes handy in case you are using scripting for creating a graph.
+You can force loading the Mermaid library if no shortcode or codefence was used by setting `mermaid.force=true`. If a shortcode or codefence was found, this option has no effect. This comes handy in case you are using scripting to render a graph.
 
 ### Setting a Specific Mermaid Theme
 

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

@@ -1,8 +1,8 @@
 +++
 aliases = "/shortcodes/swagger"
 description = "UI for your OpenAPI / Swagger specifications"
-frontmatter = ["customOpenapiURL", "disableOpenapi", "openapi.errorlevel"]
-options = ["customOpenapiURL", "disableOpenapi", "openapi.errorlevel"]
+frontmatter = ["customOpenapiURL", "openapi.errorlevel", "openapi.force"]
+options = ["customOpenapiURL", "openapi.errorlevel", "openapi.force"]
 title = "OpenAPI"
 +++
 
@@ -65,9 +65,9 @@ customOpenapiURL = "https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"
 
 ### Force Loading of the Swagger UI Library
 
-{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} The Swagger UI library will be loaded if the page contains an OpenAPI specification.
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} The Swagger UI library will be loaded if the page contains an `openapi` shortcode or codefence.
 
-You can force loading the Swagger UI library if a OpenAPI specification wasn't found by setting `disableOpenapi=false`. If an OpenAPI specification was found, the option will be ignored. This comes handy in case you are using scripting for creating an OpenAPI specification.
+You can force loading the Swagger UI library if no shortcode or codefence was used by setting `openapi.force=true`. If a shortcode or codefence was found, the option has no effect. This comes handy in case you are using scripting to render a spec.
 
 ## Example
 

hugo.toml

@@ -34,8 +34,8 @@
     noUgly = true
 
 [params.relearn.dependencies]
-  [params.relearn.dependencies.mathjax]
-    name = "MathJax"
+  [params.relearn.dependencies.math]
+    name = "Math"
   [params.relearn.dependencies.mermaid]
     name = "Mermaid"
   [params.relearn.dependencies.openapi]

layouts/partials/_relearn/dependencies.gotmpl

@@ -1,8 +1,39 @@
 {{- range .Site.Params.relearn.dependencies }}
 	{{- $has := printf "has%s" .name }}
 	{{- $disable := printf "disable%s" .name }}
-	{{- $wants := or (and (ne (index $.Params $disable) nil) (not (index $.Params $disable))) (and (ne (index $.Site.Params $disable) nil) (not (index $.Site.Params $disable))) }}
-	{{- if $wants }}
+	{{- $enable := printf "%s" (lower .name) }}
+
+	{{- $wantsPage := false }}
+	{{- if ne (index $.Params $disable) nil }}
+		{{- $wantsPage = not (index $.Params $disable) }}
+		{{- warnf "%q: DEPRECATED front matter 'disable%s' found, use '%s' or '%s.force' instead and invert the value; see https://mcshelby.github.io/hugo-theme-relearn/introduction/releasenotes/7/#7-0-0" $.File.Filename .name (lower .name) (lower .name) }}
+	{{- else if and (eq .name "Math") (ne (index $.Params "disableMathJax") nil) }}
+		{{- $wantsPage = not (index $.Params "disableMathJax") }}
+		{{- warnf "%q: DEPRECATED front matter 'disableMathJax' found, use 'math' or 'math.force' instead and invert the value; see https://mcshelby.github.io/hugo-theme-relearn/introduction/releasenotes/7/#7-0-0" $.File.Filename }}
+	{{- end }}
+	{{- with index $.Params $enable }}
+		{{- $wantsPage = or
+			(and (reflect.IsMap .) (eq (index . "force") true))
+			(and (not (reflect.IsMap .)) (eq . true))
+		}}
+	{{- end }}
+
+	{{- $wantsSite := false }}
+	{{- if ne (index $.Site.Params $disable) nil }}
+		{{- $wantsSite = not (index $.Site.Params $disable) }}
+		{{- warnf "DEPRECATED option 'disable%s' found, use '%s' or '%s.force' instead and invert the value; see https://mcshelby.github.io/hugo-theme-relearn/introduction/releasenotes/7/#7-0-0" .name (lower .name) (lower .name) }}
+	{{- else if and (eq .name "Math") (ne (index $.Site.Params "disableMathJax") nil) }}
+		{{- $wantsSite = not (index $.Site.Params "disableMathJax") }}
+		{{- warnf "DEPRECATED option 'disableMathJax' found, use 'math' or 'math.force' instead and invert the value; see https://mcshelby.github.io/hugo-theme-relearn/introduction/releasenotes/7/#7-0-0" }}
+	{{- end }}
+	{{- with index $.Site.Params $enable }}
+		{{- $wantsSite = or
+			(and (reflect.IsMap .) (eq (index . "force") true))
+			(and (not (reflect.IsMap .)) (eq . true))
+		}}
+	{{- end }}
+
+	{{- if or $wantsPage $wantsSite }}
 		{{- $.Store.Set $has true }}
 	{{- end }}
 {{- end }}

layouts/partials/shortcodes/math.html

@@ -28,5 +28,5 @@
       {{- printf " %s=%q" $k $v | safeHTMLAttr }}
     {{- end }}
   {{- end }}>{{ $content | safeHTML }}</span>
-{{- .Store.Set "hasMathJax" true }}
+{{- .Store.Set "hasMath" true }}
 {{- end }}