From b07d21c8e7b7fff9a8fb177cff0436885d378376 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6ren=20Weber?= Date: Sun, 6 Oct 2024 13:05:19 +0200 Subject: [PATCH] math: adhere to Hugo's default config params #923 --- exampleSite/config/_default/params.toml | 52 +++++++++---------- .../appearance/generator/_index.en.md | 2 +- .../content/frontmatter/frontmatter.toml | 52 +++++++++---------- .../introduction/releasenotes/7/0.en.md | 6 +++ exampleSite/content/shortcodes/math.en.md | 14 ++--- exampleSite/content/shortcodes/mermaid.en.md | 8 +-- .../content/shortcodes/openapi/_index.en.md | 8 +-- hugo.toml | 4 +- layouts/partials/_relearn/dependencies.gotmpl | 35 ++++++++++++- .../dependencies/{mathjax.html => math.html} | 0 layouts/partials/shortcodes/math.html | 2 +- 11 files changed, 109 insertions(+), 74 deletions(-) rename layouts/partials/dependencies/{mathjax.html => math.html} (100%) diff --git a/exampleSite/config/_default/params.toml b/exampleSite/config/_default/params.toml index 1d5b995005..505e885c93 100644 --- a/exampleSite/config/_default/params.toml +++ b/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 diff --git a/exampleSite/content/configuration/appearance/generator/_index.en.md b/exampleSite/content/configuration/appearance/generator/_index.en.md index 3642825308..10857f8147 100644 --- a/exampleSite/content/configuration/appearance/generator/_index.en.md +++ b/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 diff --git a/exampleSite/content/content/frontmatter/frontmatter.toml b/exampleSite/content/content/frontmatter/frontmatter.toml index 66e3098b6b..0be65a4f3f 100644 --- a/exampleSite/content/content/frontmatter/frontmatter.toml +++ b/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 diff --git a/exampleSite/content/introduction/releasenotes/7/0.en.md b/exampleSite/content/introduction/releasenotes/7/0.en.md index 9445fe197c..c0278a6f2b 100644 --- a/exampleSite/content/introduction/releasenotes/7/0.en.md +++ b/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-color` was renamed to `--MAIN-TITLES-H-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/). diff --git a/exampleSite/content/shortcodes/math.en.md b/exampleSite/content/shortcodes/math.en.md index fab346dfdb..ff487abbfa 100644 --- a/exampleSite/content/shortcodes/math.en.md +++ b/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. diff --git a/exampleSite/content/shortcodes/mermaid.en.md b/exampleSite/content/shortcodes/mermaid.en.md index 4bd20206ff..d3d762bc6f 100644 --- a/exampleSite/content/shortcodes/mermaid.en.md +++ b/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 diff --git a/exampleSite/content/shortcodes/openapi/_index.en.md b/exampleSite/content/shortcodes/openapi/_index.en.md index 4715613586..5b0a350eeb 100644 --- a/exampleSite/content/shortcodes/openapi/_index.en.md +++ b/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 diff --git a/hugo.toml b/hugo.toml index f99fcd4b35..66bb792a5e 100644 --- a/hugo.toml +++ b/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] diff --git a/layouts/partials/_relearn/dependencies.gotmpl b/layouts/partials/_relearn/dependencies.gotmpl index c5d2817bc7..167af7c935 100644 --- a/layouts/partials/_relearn/dependencies.gotmpl +++ b/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 }} \ No newline at end of file diff --git a/layouts/partials/dependencies/mathjax.html b/layouts/partials/dependencies/math.html similarity index 100% rename from layouts/partials/dependencies/mathjax.html rename to layouts/partials/dependencies/math.html diff --git a/layouts/partials/shortcodes/math.html b/layouts/partials/shortcodes/math.html index 8481dee334..40ece5a5c4 100644 --- a/layouts/partials/shortcodes/math.html +++ b/layouts/partials/shortcodes/math.html @@ -28,5 +28,5 @@ {{- printf " %s=%q" $k $v | safeHTMLAttr }} {{- end }} {{- end }}>{{ $content | safeHTML }} -{{- .Store.Set "hasMathJax" true }} +{{- .Store.Set "hasMath" true }} {{- end }} \ No newline at end of file