From 2c11f5365392945cc49a1220d8fea074b225b6ca Mon Sep 17 00:00:00 2001
From: Andreas Deininger <adeininger@urbanonline.de>
Date: Fri, 14 Oct 2022 17:23:14 +0200
Subject: [PATCH] Add render hook for 'chem' code blocks Auto activation of
 `math' and 'chem' blocks Add ability to enable KateX and/or mhchem for
 individual pages only Upgrade to KaTeX 0.16.3

---
 .../_markup/render-codeblock-chem.html        |  18 ++
 .../_markup/render-codeblock-math.html        |  28 +--
 layouts/partials/scripts.html                 |  50 +++--
 .../diagrams-and-formulae/index.md            | 182 +++++++++++++-----
 4 files changed, 192 insertions(+), 86 deletions(-)
 create mode 100644 layouts/_default/_markup/render-codeblock-chem.html

diff --git a/layouts/_default/_markup/render-codeblock-chem.html b/layouts/_default/_markup/render-codeblock-chem.html
new file mode 100644
index 0000000000..1480857725
--- /dev/null
+++ b/layouts/_default/_markup/render-codeblock-chem.html
@@ -0,0 +1,18 @@
+{{ .Page.Store.Set "hasmhchem" true -}}
+
+{{/* set default delimiters */ -}}
+{{ $delimiter_left := "$$" -}}
+{{ $delimiter_right := "$$" -}}
+
+{{/* override delimiters if set in config file */ -}}
+{{ with $.Page.Site.Params.katex.options.delimiters -}}
+  {{ range first 1 ( where . "display" true ) -}}
+    {{ $delimiter_left = index . "left" -}}
+    {{ $delimiter_right = index . "right" -}}
+  {{ end -}}
+{{ end -}}
+
+{{/* output of chemical formulae */}}
+<div class="chem">{{ $delimiter_left -}}
+{{ .Inner | safeHTML -}}
+{{ $delimiter_right -}}</div>{{ "" -}}
diff --git a/layouts/_default/_markup/render-codeblock-math.html b/layouts/_default/_markup/render-codeblock-math.html
index 831b9a2f6b..8308694906 100644
--- a/layouts/_default/_markup/render-codeblock-math.html
+++ b/layouts/_default/_markup/render-codeblock-math.html
@@ -1,16 +1,18 @@
-{{/* set default delimiters */}}
-{{ $delimiter_left := "$$" }}
-{{ $delimiter_right := "$$" }}
+{{ .Page.Store.Set "hasKaTeX" true -}}
 
-{{/* override delimiters if set in config file */}}
-{{ with $.Page.Site.Params.katex.options.delimiters }}
-  {{ range first 1 ( where . "display" true ) }}
-    {{ $delimiter_left = index . "left" }}
-    {{ $delimiter_right = index . "right" }}
-  {{ end }}
-{{end}}
+{{/* set default delimiters */ -}}
+{{ $delimiter_left := "$$" -}}
+{{ $delimiter_right := "$$" -}}
+
+{{/* override delimiters if set in config file */ -}}
+{{ with $.Page.Site.Params.katex.options.delimiters -}}
+  {{ range first 1 ( where . "display" true ) -}}
+    {{ $delimiter_left = index . "left" -}}
+    {{ $delimiter_right = index . "right" -}}
+  {{ end -}}
+{{ end -}}
 
 {{/* output of equation */}}
-<p>{{ $delimiter_left }}
-{{ .Inner | safeHTML }}
-{{ $delimiter_right }}</p>
+<div class="math">{{ $delimiter_left -}}
+{{ .Inner | safeHTML -}}
+{{ $delimiter_right }}</div>{{ "" -}}
\ No newline at end of file
diff --git a/layouts/partials/scripts.html b/layouts/partials/scripts.html
index f86ea4d96b..e225a0464a 100644
--- a/layouts/partials/scripts.html
+++ b/layouts/partials/scripts.html
@@ -1,10 +1,16 @@
+{{ $needKaTeX  := or .Site.Params.katex.enable .Params.math .Params.chem -}}
+{{ $needmhchem := or .Site.Params.katex.mhchem.enable .Params.chem -}}
 {{ $needmermaid := .Site.Params.mermaid.enable -}}
 {{ if ge hugo.Version "0.93.0" -}}
     {{ with .Site.Params.mermaid }}
         {{ $needmermaid = true }}
     {{ end }}
-    {{ $needmermaid = or $needmermaid (.Page.Store.Get "hasmermaid") -}}
-{{ end }}
+  {{ $needmermaid = or $needmermaid (.Page.Store.Get "hasmermaid") -}}
+{{ else -}}
+  {{ if or $needKaTeX $needmhchem $needmermaid -}}
+    {{ warnf "Outdated Hugo version %s, consider upgrading to make full use of all theme features" hugo.Version  }}
+  {{ end -}}
+{{ end -}}
 
 {{ if .Site.Params.markmap.enable -}}
 <style>
@@ -31,25 +37,27 @@
   <script src='{{ "js/deflate.js" | relURL }}'></script>
 {{ end -}}
 
-{{ if .Site.Params.katex.enable -}}
-<!-- load stylesheet and scripts for KaTeX support -->
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.15.1/dist/katex.min.css"
-    integrity="sha512-vJqxkZ+Sugf/6WRlpcxN01qVfX/29hF6qc33eHF1va3NgoV+U+wCi+uTAsQ10sDoGyBxHLdaHvGwDlV3yVYboA==" crossorigin="anonymous">
-<!-- The loading of KaTeX is deferred to speed up page rendering -->
-<script defer src="https://cdn.jsdelivr.net/npm/katex@0.15.1/dist/katex.min.js"
-    integrity="sha512-5ufNcHqOYgilGEHPfuRIQ5B/vDS1M8+UC+DESZ5CwVgGTg+b2Ol/15rYL/GiCWJ/Sx8oVo0FPFok1dPk8U9INQ=="
-    crossorigin="anonymous"></script>
-<!-- check whether support of mhchem is enabled in config.toml -->
-{{ if .Site.Params.katex.mhchem.enable -}}
-<!-- To add support for displaying chemical equations and physical units, load the mhchem extension: -->
-<script defer src="https://cdn.jsdelivr.net/npm/katex@0.15.1/dist/contrib/mhchem.min.js"
-    integrity="sha512-HWb6LyQhO6UkmYLjdSblpgiOvvbdkoMRjln0POPhOVbZu3l4QdqwZnMJ/cuwKScU5pWARejB495TAAAz0WNsXQ=="
-    crossorigin="anonymous"></script>
-{{ end -}}
-<!-- To automatically render math in text elements, include the auto-render extension: -->
-<script defer src='https://cdn.jsdelivr.net/npm/katex@0.15.1/dist/contrib/auto-render.min.js'
-    integrity='sha512-ZA/RPrAo88DlwRnnoNVqKINnQNcWERzRK03PDaA4GIJiVZvGFIWQbdWCsUebMZfkWohnfngsDjXzU6PokO4jGw==' crossorigin='anonymous'
-    {{ printf "onload='renderMathInElement(%s, %s);'" (( .Site.Params.katex.html_dom_element | default "document.body" ) | safeJS ) ( printf "%s" ( $.Site.Params.katex.options | jsonify )) | safeHTMLAttr }}></script>
+{{ if  $needKaTeX -}}
+{{/* load stylesheet and scripts for KaTeX support */ -}}
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.3/dist/katex.min.css"
+      integrity="sha512-6VMVcy7XQNyarhVuiL50FzpgCFKsyTd6YO93aaQEyET+BNaWvj0IgKR86Bf6+AmWczxAcSnL+JGjo+iStgO1gQ==" crossorigin="anonymous">
+  {{/* The loading of KaTeX is deferred to speed up page rendering */ -}}
+<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.3/dist/katex.min.js"
+        integrity="sha512-b9IKj4LCNrtCPBhceRcoYOHWW/S2q9fpl7iAJlyxYpykRj1SKM7FE9+E0NEnJ8g8ni47LBr2GuX9qzg/xeuwzQ=="
+        crossorigin="anonymous">
+</script>
+  {{ if $needmhchem -}}
+  {{/* To add support for displaying chemical equations and physical units, load the mhchem extension: */ -}}
+<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.3/dist/contrib/mhchem.min.js"
+        integrity="sha512-V1hl0fnOXW6Cdqe5ZVqtw8TBpJVpu3XRDRQti96j/04+tMarPrCdXEUE3UdfvfKYTpOn9DV4zEZBVr0HhDiuiQ=="
+        crossorigin="anonymous">
+</script>
+  {{ end -}}
+  {{/* To automatically render math in text elements, include the auto-render extension: */ -}}
+<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.3/dist/contrib/auto-render.min.js"
+       integrity="sha512-iWiuBS5nt6r60fCz26Nd0Zqe0nbk1ZTIQbl3Kv7kYsX+yKMUFHzjaH2+AnM6vp2Xs+gNmaBAVWJjSmuPw76Efg==" crossorigin="anonymous"
+       {{ printf "onload='renderMathInElement(%s, %s);'" (( $.Page.Site.Params.katex.html_dom_element | default "document.body" ) | safeJS ) ( printf "%s" ( $.Page.Site.Params.katex.options | jsonify )) | safeHTMLAttr }}>
+</script>
 {{ end -}}
 
 {{ $jsBs := resources.Get "vendor/bootstrap/dist/js/bootstrap.bundle.js" -}}
diff --git a/userguide/content/en/docs/adding-content/diagrams-and-formulae/index.md b/userguide/content/en/docs/adding-content/diagrams-and-formulae/index.md
index db9ee56220..1c4b62bb59 100644
--- a/userguide/content/en/docs/adding-content/diagrams-and-formulae/index.md
+++ b/userguide/content/en/docs/adding-content/diagrams-and-formulae/index.md
@@ -3,6 +3,8 @@ title: "Diagrams and Formulae"
 linkTitle: "Diagrams and Formulae"
 weight: 11
 description: Add generated diagrams and scientific formulae to your site.
+math: true
+chem: true
 ---
 
 Docsy has built-in support for a number of diagram creation and typesetting tools you can use to add rich content to your site, including \\(\KaTeX\\), Mermaid, Diagrams.net, PlantUML, and MarkMap.
@@ -11,51 +13,84 @@ Docsy has built-in support for a number of diagram creation and typesetting tool
 
 [\\(\LaTeX\\)](https://www.latex-project.org/) is a high-quality typesetting system for the production of technical and scientific documentation. Due to its excellent math typesetting capabilities, \\(\TeX\\) became the de facto standard for the communication and publication of scientific documents, especially if these documents contain a lot of mathematical formulae. Designed and mostly written by Donald Knuth, the initial version was released in 1978. Dating back that far, \\(\LaTeX\\) has `pdf` as its primary output target and is not particularly well suited for producing HTML output for the Web. Fortunately, with [\\(\KaTeX\\)](https://katex.org/) there exists a fast and easy-to-use JavaScript library for \\(\TeX\\) math rendering on the web, which was integrated into the Docsy theme.
 
-With \\(\KaTeX\\) support enabled in Docsy, you can include complex mathematical formulae into your web page, either inline or centred on its own line. Since \\(\KaTeX\\) relies on server side rendering, it produces the same output regardless of your browser or your environment. Formulae can be shown either inline or in display mode:
+With \\(\KaTeX\\) support [enabled](#activating-and-configuring-katex-support) in Docsy, you can include complex mathematical formulae into your web page, either inline or centred on its own line. Since \\(\KaTeX\\) relies on server side rendering, it produces the same output regardless of your browser or your environment. Formulae can be shown either inline or in display mode:
 
 ### Inline formulae
 
 The following code sample produces a text line with three inline formulae:
 
 ```tex
-When \\(a \ne 0\\), there are two solutions to \\(ax^2 + bx + c= 0\\) and they are \\(x = {-b \pm \sqrt{b^2-4ac} \over 2a}.\\)
+When \\(a \ne 0\\), there are two solutions to \\(ax^2 + bx + c= 0\\) and they are \\(x = {-b \pm \sqrt{b^2-4ac} \over 2a}\\).
 ```
 
-When \\(a \ne 0\\), there are two solutions to \\(ax^2 + bx + c= 0\\) and they are \\(x = {-b \pm \sqrt{b^2-4ac} \over 2a}.\\)
+When \\(a \ne 0\\), there are two solutions to \\(ax^2 + bx + c= 0\\) and they are \\(x = {-b \pm \sqrt{b^2-4ac} \over 2a}\\).
 
 ### Formulae in display mode
 
-The following code sample produces an introductory text line followed by a formula numbered as `(1)` residing on her own line:
+The following code sample produces an introductory text line followed by a formula numbered as `(1)` residing on its own line:
 
-```tex
+````markdown
 The probability of getting \\(k\\) heads when flipping \\(n\\) coins is:
-$$
+```math
 \tag*{(1)} P(E) = {n \choose k} p^k (1-p)^{n-k}
-$$
 ```
+````
+
+The formula itself is written inside a [GLFM math block](https://docs.gitlab.com/ee/user/markdown.html#math). The above code fragment renders to:
 
 The probability of getting \\(k\\) heads when flipping \\(n\\) coins is:
-$$
+```math
 \tag*{(1)}  P(E) = {n \choose k} p^k (1-p)^{n-k}
-$$
+```
 
-You can also use [GLFM's math blocks](https://docs.gitlab.com/ee/user/markdown.html#math) (requires hugo 0.93 or newer):
-````markdown
-```math
+{{% alert title="Warning" color="warning" %}}
+`math` code blocks are only supported as of hugo version 0.93.
+
+In case of hugo version 0.92 or lower, use this code snippet to display the formula:
+```tex
+$$
 \tag*{(1)} P(E) = {n \choose k} p^k (1-p)^{n-k}
+$$
 ```
-````
+{{% /alert %}}
 
 {{% alert title="Tip" %}}
 This [wiki page](https://en.wikibooks.org/wiki/LaTeX/Mathematics) provides in-depth information about typesetting mathematical formulae using the \\(\LaTeX\\) typesetting system.
 {{% /alert %}}
 
-### Enabling and configuring \\(\LaTeX\\) support
+### Activating and configuring \\(\KaTeX\\) support
+
+#### Auto activation
+
+As soon as you use a `math` code block on your page, support of \\(\KaTeX\\) is automatically enabled.
+
+#### Manual activation (no `math` code block present or hugo 0.92 or lower)
 
-To enable/disable \\(\KaTeX\\) support inside the Docsy theme, update `config.toml`/`config.yaml`/`config.json`:
+If you want to use inline formulae and don't have a `math` code block present in your page which triggers auto activation, you need to manually activate \\(\KaTeX\\) support. The easiest way to do so is to add a `math` attribute to the frontmatter of your page and set it to `true`:
 
 {{< tabpane persistLang=false >}}
-{{< tab header="Configuration file:" disabled=true />}}
+{{< tab header="Page front matter:" disabled=true />}}
+{{< tab header="toml" lang="toml" >}}
++++
+math = true
++++
+{{< /tab >}}
+{{< tab header="yaml" lang="yaml" >}}
+---
+math: true
+---
+{{< /tab >}}
+{{< tab header="json" lang="json" >}}
+{
+  "math": true
+}
+{{< /tab >}}
+{{< /tabpane >}}
+
+If you use formulae in most of your pages, you can also enable sitewide \\(\KaTeX\\) support inside the Docsy theme. To do so update `config.toml`/`config.yaml`/`config.json`:
+
+{{< tabpane persistLang=false >}}
+{{< tab header="Site configuration file:" disabled=true />}}
 {{< tab header="config.toml" lang="toml" >}}
 [params.katex]
 enable = true
@@ -79,7 +114,7 @@ params:
 Additionally, you can customize various \\(\KaTeX\\) options inside `config.toml`/`config.yaml`/`config.json`, if needed:
 
 {{< tabpane persistLang=false >}}
-{{< tab header="Configuration file:" disabled=true />}}
+{{< tab header="Site configuration file:" disabled=true />}}
 {{< tab header="config.toml" lang="toml" >}}
 [params.katex]
 # enable/disable KaTeX support
@@ -192,10 +227,86 @@ For a complete list of options and their detailed description, have a look at th
 
 ### Display of Chemical Equations and Physical Units
 
-[mhchem](https://www.ctan.org/pkg/mhchem) is a \\(\LaTeX\\) package for typesetting chemical molecular formulae and equations. Fortunately, \\(\KaTeX\\) provides the `mhchem` [extension](https://github.com/KaTeX/KaTeX/tree/main/contrib/mhchem) that makes the `mhchem` package accessible when authoring content for the web. Since this extension was integrated into the Docsy theme, you can write beautiful chemical equations easily once `mhchem` support is enabled inside your `config.toml`/`config.yaml`/`config.json`:
+[mhchem](https://www.ctan.org/pkg/mhchem) is a \\(\LaTeX\\) package for typesetting chemical molecular formulae and equations. Fortunately, \\(\KaTeX\\) provides the `mhchem` [extension](https://github.com/KaTeX/KaTeX/tree/main/contrib/mhchem) that makes the `mhchem` package accessible when authoring content for the web. With `mhchem` extension [enabled](#activating-rendering-support-for-chemical-formulae), you can easily include chemical equations into your page. An equation can be shown either inline or can reside on its own line. The following code sample produces a text line including a chemical equation:
+
+```mhchem
+*Precipitation of barium sulfate:* \\(\ce{SO4^2- + Ba^2+ -> BaSO4 v}\\)
+```
+
+*Precipitation of barium sulfate:* \\(\ce{SO4^2- + Ba^2+ -> BaSO4 v}\\)
+
+More complex equations need to be displayed on their own line. Use a code block adorned with `chem` in order to achieve this:
+
+````markdown
+```chem
+\tag*{(2)} \ce{Zn^2+  <=>[+ 2OH-][+ 2H+]  $\underset{\text{amphoteric hydroxide}}{\ce{Zn(OH)2 v}}$  <=>[+ 2OH-][+ 2H+]  $\underset{\text{tetrahydroxozincate}}{\ce{[Zn(OH)4]^2-}}$}
+```
+````
+
+```chem
+\tag*{(2)} \ce{Zn^2+  <=>[+ 2OH-][+ 2H+]  $\underset{\text{amphoteric hydroxide}}{\ce{Zn(OH)2 v}}$  <=>[+ 2OH-][+ 2H+]  $\underset{\text{tetrahydroxozincate}}{\ce{[Zn(OH)4]^2-}}$}
+```
+
+{{% alert title="Warning" color="warning" %}}
+`chem` code blocks are only supported as of hugo version 0.93.
+
+In case of hugo version 0.92 or lower, use this code snippet to display the formula:
+```tex
+$$
+\tag*{(2)} \ce{Zn^2+  <=>[+ 2OH-][+ 2H+]  $\underset{\text{amphoteric hydroxide}}{\ce{Zn(OH)2 v}}$  <=>[+ 2OH-][+ 2H+]  $\underset{\text{tetrahydroxozincate}}{\ce{[Zn(OH)4]^2-}}$}
+$$
+```
+{{% /alert %}}
+
+{{% alert title="Note" %}}
+The [manual](https://mhchem.github.io/MathJax-mhchem/) for mchem’s input syntax provides in-depth information about typesetting chemical formulae and physical units using the `mhchem` tool.
+{{% /alert %}}
+
+Use of `mhchem` is not limited to the authoring of chemical equations, using the included `\pu` command, pretty looking physical units can be written with ease, too. The following code sample produces two text lines with four numbers plus their corresponding physical units:
+
+```mhchem
+* Scientific number notation: \\(\pu{1.2e3 kJ}\\) or \\(\pu{1.2E3 kJ}\\) \\
+* Divisions: \\(\pu{123 kJ/mol}\\) or \\(\pu{123 kJ//mol}\\)
+```
+
+* Scientific number notation: \\(\pu{1.2e3 kJ}\\) or \\(\pu{1.2E3 kJ}\\)
+* Divisions: \\(\pu{123 kJ/mol}\\) or \\(\pu{123 kJ//mol}\\)
+
+For a complete list of options when authoring physical units, have a look at the [section](https://mhchem.github.io/MathJax-mhchem/#pu) on physical units in the `mhchem` documentation.
+
+#### Activating rendering support for chemical formulae
+
+##### Auto activation
+
+As soon as you use a `chem` code block on your page, rendering support for chemical equations is automatically enabled.
+
+##### Manual activation (no `chem` code block present or hugo 0.92 or lower)
+
+If you want to use chemical formulae inline and don't have a `chem` code block present in your page which triggers auto activation, you need to manually activate rendering support for chemical formulae. The easiest way to do so is to add a `chem` attribute to the frontmatter of your page and set it to `true`:
 
 {{< tabpane persistLang=false >}}
-{{< tab header="Configuration file:" disabled=true />}}
+{{< tab header="Page front matter:" disabled=true />}}
+{{< tab header="toml" lang="toml" >}}
++++
+chem = true
++++
+{{< /tab >}}
+{{< tab header="yaml" lang="yaml" >}}
+---
+chem: true
+---
+{{< /tab >}}
+{{< tab header="json" lang="json" >}}
+{
+  "chem": true
+}
+{{< /tab >}}
+{{< /tabpane >}}
+
+If you use formulae in most of your pages, you can also enable sitewide rendering support for chemical formulae inside the Docsy theme. To do so, enable `mhchem` inside your `config.toml`/`config.yaml`/`config.json`:
+
+{{< tabpane persistLang=false >}}
+{{< tab header="Site configuration file:" disabled=true />}}
 {{< tab header="config.toml" lang="toml" >}}
 [params.katex]
 enable = true
@@ -224,39 +335,6 @@ params:
 {{< /tab >}}
 {{< /tabpane >}}
 
-
-With `mhchem` extension enabled, you can easily include chemical equations into your page. The equations can be shown either inline or can reside on its own line. The following code sample produces a text line including a chemical equation:
-
-```mhchem
-*Precipitation of barium sulfate:* \\(\ce{SO4^2- + Ba^2+ -> BaSO4 v}\\)
-```
-
-*Precipitation of barium sulfate:* \\(\ce{SO4^2- + Ba^2+ -> BaSO4 v}\\)
-
-More complex equations, like the one shown in the code sample below, should be displayed on their own line:
-
-```mhchem
-$$\tag*{(2)} \ce{Zn^2+  <=>[+ 2OH-][+ 2H+]  $\underset{\text{amphoteric hydroxide}}{\ce{Zn(OH)2 v}}$  <=>[+ 2OH-][+ 2H+]  $\underset{\text{tetrahydroxozincate}}{\ce{[Zn(OH)4]^2-}}$}$$
-```
-
-$$\tag*{(2)} \ce{Zn^2+  <=>[+ 2OH-][+ 2H+]  $\underset{\text{amphoteric hydroxide}}{\ce{Zn(OH)2 v}}$  <=>[+ 2OH-][+ 2H+]  $\underset{\text{tetrahydroxozincate}}{\ce{[Zn(OH)4]^2-}}$}$$
-
-{{% alert title="Tip" %}}
-The [manual](https://mhchem.github.io/MathJax-mhchem/) for mchem’s input syntax provides in-depth information about typesetting chemical formulae and physical units using the `mhchem` tool.
-{{% /alert %}}
-
-Use of `mhchem` is not limited to the authoring of chemical equations, using the included `\pu` command, pretty looking physical units can be written with ease, too. The following code sample produces two text lines with four numbers plus their corresponding physical units:
-
-```mhchem
-* Scientific number notation: \\(\pu{1.2e3 kJ}\\) or \\(\pu{1.2E3 kJ}\\) \\
-* Divisions: \\(\pu{123 kJ/mol}\\) or \\(\pu{123 kJ//mol}\\)
-```
-
-* Scientific number notation: \\(\pu{1.2e3 kJ}\\) or \\(\pu{1.2E3 kJ}\\)
-* Divisions: \\(\pu{123 kJ/mol}\\) or \\(\pu{123 kJ//mol}\\)
-
-For a complete list of options when authoring physical units, have a look at the [section](https://mhchem.github.io/MathJax-mhchem/#pu) on physical units in the `mhchem` documentation.
-
 ## Diagrams with Mermaid
 
 [Mermaid](https://mermaid-js.github.io) is a Javascript library for rendering simple text definitions to useful diagrams in the browser.  It can generate a variety of different diagram types, including flowcharts, sequence diagrams, class diagrams, state diagrams, ER diagrams, user journey diagrams, Gantt charts and pie charts.