From a9d6c1b7e6bd48559f1e59c7d56049c9d46e8124 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6ren=20Weber?= Date: Fri, 19 Apr 2024 23:37:00 +0200 Subject: [PATCH] math: allow to work with Hugo's passthrough configuration #832 --- exampleSite/config/_default/hugo.toml | 13 +++++ .../content/basics/migration/_index.en.md | 2 + exampleSite/content/shortcodes/math.en.md | 57 ++++++++++++++++++- layouts/partials/dependencies/mathjax.html | 14 +---- 4 files changed, 71 insertions(+), 15 deletions(-) diff --git a/exampleSite/config/_default/hugo.toml b/exampleSite/config/_default/hugo.toml index 64ede84f9e..d60d6cfd9d 100644 --- a/exampleSite/config/_default/hugo.toml +++ b/exampleSite/config/_default/hugo.toml @@ -63,6 +63,19 @@ title = "Hugo Relearn Theme" # if in doubt, remove this line renderer.unsafe = true + [markup.goldmark.extensions] + + [markup.goldmark.extensions.passthrough] + enable = true + + [markup.goldmark.extensions.passthrough.delimiters] + # the settings chosen here match the default initialization + # of the MathJax library chosen by the theme; + # if you want to adjust to different values you also need + # to set them in `[params] mathJaxInitialize` + inline = [['\(', '\)'], ['$', '$']] + block = [['\[', '\]'], ['$$', '$$']] + # showcase of the menu shortcuts; you can use relative URLs linking # to your content or use fully-qualified URLs to link outside of # your project diff --git a/exampleSite/content/basics/migration/_index.en.md b/exampleSite/content/basics/migration/_index.en.md index 690c2b5d77..3b71ee0bd8 100644 --- a/exampleSite/content/basics/migration/_index.en.md +++ b/exampleSite/content/basics/migration/_index.en.md @@ -40,6 +40,8 @@ This document shows you what's new in the latest release and flags it with one o - {{% badge style="note" title=" " %}}Change{{% /badge %}} The [`include` shortcode](shortcodes/include) is now able to resolve links to resources as well as to files in the file system (the old behavior). You can configure to generate warnings or errors during build by setting `include.errorlevel` to either `warning` or `error` in your `hugo.toml` if a path can not be resolved. +- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Math is now usable without enclosing it in a shortcode or codefence by using Hugo's [passthrough configuration](shortcodes/math#passthrough-configuration). + - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Translation into Romanian. --- diff --git a/exampleSite/content/shortcodes/math.en.md b/exampleSite/content/shortcodes/math.en.md index 78784084b5..f8bbfcb6d2 100644 --- a/exampleSite/content/shortcodes/math.en.md +++ b/exampleSite/content/shortcodes/math.en.md @@ -5,6 +5,8 @@ title = "Math" The `math` shortcode generates beautiful formatted math and chemical formulae using the [MathJax](https://mathjax.org/) library. +Math is also [usable without enclosing it](https://gohugo.io/content-management/mathematics) in a shortcode or codefence but [requires configuration](#passthrough-configuration) by you. + {{< math align="center" >}} $$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$ {{< /math >}} @@ -42,7 +44,13 @@ $$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \ "content" "$$left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$" "align" "center" )}} +```` +{{% /tab %}} +{{% tab title="passthrough" %}} + +````md +$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$ ```` {{% /tab %}} @@ -57,7 +65,7 @@ $$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \ ## Configuration -MathJax is configured with default settings. You can customize MathJax's default settings for all of your files through a JSON object in your `hugo.toml` or override these settings per page through your pages frontmatter. +MathJax is configured with default settings but you can customize MathJax's default settings for all of your files through a JSON object in your `hugo.toml` or override these settings per page through your pages frontmatter. The JSON object of your `hugo.toml` / frontmatter is forwarded into MathJax's configuration object. @@ -65,15 +73,42 @@ See [MathJax documentation](https://docs.mathjax.org/en/latest/options/index.htm ### Global Configuration File +This example reflects the default configuration also used if you don't define `mathJaxInitialize` + {{< multiconfig file=hugo >}} [params] - mathJaxInitialize = "{ \"chtml\": { \"displayAlign\": \"left\" } }" + mathJaxInitialize = "{ \"tex\": { \"inlineMath\": [[\"\\(\", \"\\)\"], [\"$\", \"$\"]], displayMath: [[\"\\[\", \"\\]\"], [\"$$\", \"$$\"]] }, \"options\": { \"enableMenu\": false }" {{< /multiconfig >}} ### Page's Frontmatter +Usually you don't need to redefine the global initialization settings for a single page. But if you do, you have repeat all the values from your global configuration you want to keep for a single page as well. + +Eg. If you have redefined the delimiters to something exotic like `@` symbols in your global config, but want to additionally align your math to the left for a specific page, you have to put this to your frontmatter: + {{< multiconfig fm=true >}} -mathJaxInitialize = "{ \"chtml\": { \"displayAlign\": \"left\" } }" +mathJaxInitialize = "{ \"chtml\": { \"displayAlign\": \"left\" }, { \"tex\": { \"inlineMath\": [[\"\\(\", \"\\)\"], [\"@\", \"@\"]], displayMath: [[\"\\[\", \"\\]\"], [\"@@\", \"@@\"]] }, \"options\": { \"enableMenu\": false }" +{{< /multiconfig >}} + +### Passthrough Configuration + +Since {{% badge color="fuchsia" icon="fa-fw fab fa-hackerrank" title=" " %}}0.120.0{{% /badge %}} you can use your math without enclosing it in a shortcode or codefence by using a [passthrough configuration](https://gohugo.io/content-management/mathematics/#step-1) in your `hugo.toml`: + +{{< multiconfig file=hugo >}} +[markup] + [markup.goldmark] + [markup.goldmark.extensions] + [markup.goldmark.extensions.passthrough] + enable = true + [markup.goldmark.extensions.passthrough.delimiters] + block = [['\[', '\]'], ['$$', '$$']] + inline = [['\(', '\)']] +{{< /multiconfig >}} + +In this case you have to tell the theme that your page contains math by setting this in your page's frontmatter: + +{{< multiconfig fm=true >}} +disableMathJax = false {{< /multiconfig >}} ## Examples @@ -116,6 +151,22 @@ $$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \ $$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$ ```` +### Passthrough + +````md +$$\left| +\begin{array}{cc} +a & b \\ +c & d +\end{array}\right|$$ +```` + +$$\left| +\begin{array}{cc} +a & b \\ +c & d +\end{array}\right|$$ + ### Chemical Formulae ````md diff --git a/layouts/partials/dependencies/mathjax.html b/layouts/partials/dependencies/mathjax.html index 3c0ba9c921..9b52ba8168 100644 --- a/layouts/partials/dependencies/mathjax.html +++ b/layouts/partials/dependencies/mathjax.html @@ -11,19 +11,9 @@