diff --git a/.cspell.json b/.cspell.json
index 1c386ee29..b8ea0610f 100644
--- a/.cspell.json
+++ b/.cspell.json
@@ -106,8 +106,10 @@
"eopkg",
"gitee",
"goldmark",
+ "KaTeX",
"kubuntu",
"lubuntu",
+ "MathJax",
"nosql",
"pandoc",
"pkgin",
diff --git a/config/_default/markup.toml b/config/_default/markup.toml
index fb68fae23..a0c1e83a7 100644
--- a/config/_default/markup.toml
+++ b/config/_default/markup.toml
@@ -1,6 +1,5 @@
defaultMarkdownHandler = "goldmark"
-[goldmark]
[goldmark.extensions]
definitionList = true
footnote = true
@@ -9,12 +8,22 @@ strikethrough = true
table = true
taskList = true
typographer = true
+
+ [goldmark.extensions.passthrough]
+ enable = true
+
+ [goldmark.extensions.passthrough.delimiters]
+ block = [['\[', '\]'], ['$$', '$$']]
+ inline = [['\(', '\)']]
+
[goldmark.parser]
autoHeadingID = true
autoHeadingIDType = "github"
-[goldmark.parser.attribute]
-block = true
-title = true
+
+ [goldmark.parser.attribute]
+ block = true
+ title = true
+
[goldmark.renderer]
hardWraps = false
unsafe = false
@@ -28,4 +37,4 @@ noClasses = false
[tableOfContents]
endLevel = 2
ordered = false
-startLevel = 2
\ No newline at end of file
+startLevel = 2
diff --git a/config/_default/params.toml b/config/_default/params.toml
index dddd53b5b..378c8071e 100644
--- a/config/_default/params.toml
+++ b/config/_default/params.toml
@@ -1,6 +1,5 @@
-
description = "The world’s fastest framework for building websites"
-## Setting this to true will add a "noindex" to *EVERY* page on the site..
+## Setting this to true will add a "noindex" to *EVERY* page on the site.
removefromexternalsearch = false
## Gh repo for site footer (include trailing slash)
ghrepo = "https://github.com/gohugoio/hugoDocs/"
@@ -12,6 +11,8 @@ ghdocsrepo = "https://github.com/gohugoio/hugoDocs/tree/master/docs"
forum = "https://discourse.gohugo.io/"
## Google Tag Manager
gtmid = ""
+## Setting this to true will load layouts/partials/math.html on every page on the site.
+math = false
# First one is picked as the Twitter card image if not set on page.
images = ["images/gohugoio-card.png"]
diff --git a/content/en/content-management/mathematics.md b/content/en/content-management/mathematics.md
new file mode 100644
index 000000000..d2c71e630
--- /dev/null
+++ b/content/en/content-management/mathematics.md
@@ -0,0 +1,227 @@
+---
+title: Mathematics in markdown
+linkTitle: Mathematics
+description: Include mathematical equations and expressions in your markdown using LaTeX or TeX typsetting syntax.
+categories: [content management]
+keywords: [chemical,chemistry,latex,math,mathjax,tex,typsetting]
+menu:
+ docs:
+ parent: content-management
+ weight: 250
+weight: 250
+toc: true
+math: true
+---
+
+{{< new-in 0.122.0 >}}
+
+\[
+\begin{aligned}
+KL(\hat{y} || y) &= \sum_{c=1}^{M}\hat{y}_c \log{\frac{\hat{y}_c}{y_c}} \\
+JS(\hat{y} || y) &= \frac{1}{2}(KL(y||\frac{y+\hat{y}}{2}) + KL(\hat{y}||\frac{y+\hat{y}}{2}))
+\end{aligned}
+\]
+
+## Overview
+
+Mathematical equations and expressions authored in [LaTeX] or [TeX] are common in academic and scientific publications. Your browser typically renders this mathematical markup using an open-source JavaScript display engine such as [MathJax] or [KaTeX].
+
+For example, this is the mathematical markup for the equations displayed at the top of this page:
+
+```text
+\[
+\begin{aligned}
+KL(\hat{y} || y) &= \sum_{c=1}^{M}\hat{y}_c \log{\frac{\hat{y}_c}{y_c}} \\
+JS(\hat{y} || y) &= \frac{1}{2}(KL(y||\frac{y+\hat{y}}{2}) + KL(\hat{y}||\frac{y+\hat{y}}{2}))
+\end{aligned}
+\]
+```
+
+Equations and expressions can be displayed inline with other text, or as standalone blocks. Block presentation is also known as "display" mode.
+
+Whether an equation or expression appears inline, or as a block, depends on the delimiters that surround the mathematical markup. Delimiters are defined in pairs, where each pair consists of an opening and closing delimiter. The opening and closing delimiters may be the same, or different. Common delimiter pairs are shown in [Step 1].
+
+The approach described below avoids reliance on platform-specific features like shortcodes or code block render hooks. Instead, it utilizes a standardized markup format for mathematical equations and expressions, compatible with the rendering engines used by GitHub, GitLab, [Microsoft VS Code], [Obsidian], [Typora], and others.
+
+## Setup
+
+Follow these instructions to include mathematical equations and expressions in your markdown using LaTeX or TeX typsetting syntax.
+
+###### Step 1
+
+Enable and configure the Goldmark [passthrough extension] in your site configuration. The passthrough extension preserves raw markdown within delimited snippets of text, including the delimiters themselves.
+
+{{< code-toggle file=hugo copy=true >}}
+[markup.goldmark.extensions.passthrough]
+enable = true
+
+[markup.goldmark.extensions.passthrough.delimiters]
+block = [['\[', '\]'], ['$$', '$$']]
+inline = [['\(', '\)']]
+
+[params]
+math = true
+{{< /code-toggle >}}
+
+The configuration above enables mathematical rendering on every page unless you set the `math` parameter to `false` in front matter. To enable mathematical rendering as needed, set the `math` parameter to `false` in your site configuration, and set the `math` parameter to `true` in front matter. Use this parameter in your base template as shown in [Step 3].
+
+{{% note %}}
+The configuration above precludes the use of the `$...$` delimiter pair for inline equations. Although you can add this delimiter pair to the configuration and JavaScript, you will need to double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting.
+
+See the [inline delimiters](#inline-delimiters) section for details.
+{{% /note %}}
+
+To disable passthrough of inline snippets, omit the `inline` key from the configuration:
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.extensions.passthrough.delimiters]
+block = [['\[', '\]'], ['$$', '$$']]
+{{< /code-toggle >}}
+
+You can define your own opening and closing delimiters, provided they match the delimiters that you set in [Step 2].
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.extensions.passthrough.delimiters]
+block = [['@@', '@@']]
+inline = [['@', '@']]
+{{< /code-toggle >}}
+
+###### Step 2
+
+Create a partial template to load MathJax or KaTeX. The example below loads MathJax, or you can use KaTeX as described in the [engines](#engines) section.
+
+{{< code file=layouts/partials/math.html copy=true >}}
+
+
+{{< /code >}}
+
+The delimiters above must match the delimiters in your site configuration.
+
+###### Step 3
+
+Conditionally call the partial template from the base template.
+
+{{< code file=layouts/_default/baseof.html >}}
+
+ ...
+ {{ if .Param "math" }}
+ {{ partialCached "math.html" . }}
+ {{ end }}
+ ...
+
+{{< /code >}}
+
+The example above loads the partial template if you have set the `math` parameter in front matter to `true`. If you have not set the `math` parameter in front matter, the conditional statement falls back to the `math` parameter in your site configuration.
+
+###### Step 4
+
+Include mathematical equations and expressions in your markdown using LaTeX or TeX typsetting syntax.
+
+{{< code file=content/math-examples.md copy=true >}}
+This is an inline \(a^*=x-b^*\) equation.
+
+These are block equations:
+
+\[a^*=x-b^*\]
+
+\[ a^*=x-b^* \]
+
+\[
+a^*=x-b^*
+\]
+
+These are block equations using alternate delimiters:
+
+$$a^*=x-b^*$$
+
+$$ a^*=x-b^* $$
+
+$$
+a^*=x-b^*
+$$
+{{< /code >}}
+
+If you set the `math` parameter to `false` in your site configuration, you must set the `math` parameter to `true` in front matter. For example:
+
+{{< code-toggle file=content/math-examples.md fm=true >}}
+title = 'Math examples'
+math = true
+date = 2024-01-24T18:09:49-08:00
+{{< /code-toggle >}}
+
+## Inline delimiters
+
+The configuration, JavaScript, and examples above use the `\(...\)` delimiter pair for inline equations. The `$...$` delimiter pair is a common alternative, but using it may result in unintended formatting if you use the `$` symbol outside of math contexts.
+
+If you add the `$...$` delimiter pair to your configuration and JavaScript, you must double-escape the `$` when outside of math contexts, regardless of whether mathematical rendering is enabled on the page. For example:
+
+```text
+A \\$5 bill _saved_ is a \\$5 bill _earned_.
+```
+
+{{% note %}}
+If you use the `$...$` delimiter pair for inline equations, and occasionally use the `$` symbol outside of math contexts, you must use MathJax instead of KaTeX to avoid unintended formatting caused by [this KaTeX limitation](https://github.com/KaTeX/KaTeX/issues/437).
+{{% /note %}}
+
+## Engines
+
+MathJax and KaTeX are open-source JavaScript display engines. Both engines are fast, but at the time of this writing MathJax v3.2.2 is slightly faster than KaTeX v0.16.9.
+
+{{% note %}}
+If you use the `$...$` delimiter pair for inline equations, and occasionally use the `$` symbol outside of math contexts, you must use MathJax instead of KaTeX to avoid unintended formatting caused by [this KaTeX limitation](https://github.com/KaTeX/KaTeX/issues/437).
+
+See the [inline delimiters](#inline-delimiters) section for details.
+{{% /note %}}
+
+To use KaTeX instead of MathJax, replace the partial template from [Step 2] with this:
+
+{{< code file=layouts/partials/math.html copy=true >}}
+
+
+
+
+{{< /code >}}
+
+The delimiters above must match the delimiters in your site configuration.
+
+## Chemistry
+
+Both MathJax and KaTeX provide support for chemical equations. For example:
+
+```text
+$$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$
+```
+
+$$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$
+
+As shown in [Step 2] above, MathJax supports chemical equations without additional configuration. To add chemistry support to KaTeX, enable the mhchem extension as described in the KaTeX [documentation](https://katex.org/docs/libs).
+
+[KaTeX]: https://katex.org/
+[LaTeX]: https://www.latex-project.org/
+[MathJax]: https://www.mathjax.org/
+[Microsoft VS Code]: https://code.visualstudio.com/
+[Obsidian]: https://obsidian.md/
+[Step 1]: #step-1
+[Step 2]: #step-2
+[Step 3]: #step-3
+[TeX]: https://en.wikipedia.org/wiki/TeX
+[Typora]: https://typora.io/
+[passthrough extension]: https://github.com/gohugoio/hugo-goldmark-extensions
diff --git a/layouts/_default/baseof.html b/layouts/_default/baseof.html
new file mode 100644
index 000000000..63b5b10f5
--- /dev/null
+++ b/layouts/_default/baseof.html
@@ -0,0 +1,123 @@
+
+
+
+
+ {{/* https://www.zachleat.com/web/preload/ */}}
+
+
+
+
+
+ {{/* NOTE: the Site's title, and if there is a page title, that is set too */}}
+
+ {{ block "title" . }}
+ {{ with .Title }}{{ . }} | {{ end }}{{ .Site.Title }}
+ {{ end }}
+
+
+
+
+ {{ hugo.Generator }}
+
+ {{ if hugo.IsProduction }}
+
+ {{ else }}
+
+ {{ end }}
+
+ {{ range .AlternativeOutputFormats -}}
+
+ {{ end -}}
+
+ {{ $isDev := eq hugo.Environment "development" }}
+ {{ $stylesheet := resources.Get "output/css/app.css" }}
+ {{ if not $isDev }}
+ {{ $stylesheet = $stylesheet | minify | fingerprint }}
+ {{ end }}
+ {{ with $stylesheet }}
+ {{ if $isDev }}
+
+ {{ else }}
+
+ {{ end }}
+ {{ $.Scratch.Set "stylesheet" . }}
+ {{ end }}
+
+
+
+
+ {{ block "scripts" . }}
+ {{- partial "site-scripts.html" . -}}
+ {{ end }}
+ {{ partial "site-manifest.html" . }}
+ {{- partial "head-additions.html" . -}}
+ {{- partial "opengraph/opengraph.html" . -}}
+ {{- template "_internal/schema.html" . -}}
+ {{- partial "opengraph/twitter_cards.html" . -}}
+
+ {{ if hugo.IsProduction }}
+ {{ partial "gtag.html" . }}
+ {{ end }}
+
+ {{ if .Param "math" }}
+ {{ partialCached "math.html" . }}
+ {{ end }}
+
+
+
+
+ {{ partial "hooks/after-body-start.html" . }}
+ {{ block "nav" . }}{{ partial "site-nav.html" . }}{{ end }}
+ {{ block "header" . }}{{ end }}
+
+ {{ block "main" . }}{{ end }}
+
+
+ {{ block "footer" . }}{{ partialCached "site-footer.html" . }}{{ end }}
+
+ {{ partial "hooks/before-body-end.html" . }}
+
+
+
diff --git a/layouts/partials/math.html b/layouts/partials/math.html
new file mode 100644
index 000000000..defcaa055
--- /dev/null
+++ b/layouts/partials/math.html
@@ -0,0 +1,9 @@
+
+