math: allow to work with Hugo's passthrough configuration #832

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

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.
 
 ---

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

layouts/partials/dependencies/mathjax.html

@@ -11,19 +11,9 @@
     <script>
       function useMathJax( config ){
         window.MathJax = Object.assign( window.MathJax || {}, {
-          loader: {
-            load: ['[tex]/mhchem']
-          },
-          startup: {
-            elements: [
-              '.math'
-            ]
-          },
           tex: {
-            inlineMath: [
-              ['$', '$'], // allow for single dollars as we set startup.elements
-              ['\\(', '\\)']
-            ]
+            inlineMath:  [['\\(', '\\)'], ['$',  '$']],  // inline
+            displayMath: [['\\[', '\\]'], ['$$', '$$']], // block
           },
           options: {
             enableMenu: false // avoid translation hassle for context menu