From 7031718449830fb5d2faa6342b947961ff293820 Mon Sep 17 00:00:00 2001
From: Xin <5097752+imfing@users.noreply.github.com>
Date: Sat, 14 Jun 2025 14:36:10 +0100
Subject: [PATCH] feat(math): add optional MathJax support (#707)

* feat: add MathJax option

* docs: move math engine note

* refactor: update LaTeX documentation and improve MathJax integration

- Adjusted LaTeX documentation for clarity and formatting.
- Enhanced MathJax configuration in the templates to support both KaTeX and MathJax rendering.
- Removed deprecated comments and streamlined the script loading process for MathJax.
- Updated the passthrough extension settings in the Hugo configuration for better compatibility with LaTeX math expressions.

* docs: simplify LaTeX documentation and clarify configuration steps

- Updated LaTeX documentation to reflect that KaTeX is enabled by default, removing the need for manual activation.
- Added examples for using LaTeX math expressions and clarified the configuration for the passthrough extension in Hugo.
- Enhanced MathJax section to emphasize its use as an alternative rendering engine.
---
 exampleSite/content/docs/guide/latex.fa.md    | 77 +++++++++++++++----
 exampleSite/content/docs/guide/latex.ja.md    | 70 ++++++++++-------
 exampleSite/content/docs/guide/latex.md       | 61 ++++++++++-----
 exampleSite/content/docs/guide/latex.zh-cn.md | 67 +++++++++-------
 exampleSite/hugo.yaml                         |  2 +-
 layouts/_markup/render-passthrough.html       | 25 ++++--
 layouts/_partials/head.html                   |  5 +-
 layouts/_partials/scripts/mathjax.html        | 21 +++++
 layouts/_partials/tags.html                   | 10 +--
 9 files changed, 236 insertions(+), 102 deletions(-)
 create mode 100644 layouts/_partials/scripts/mathjax.html

diff --git a/exampleSite/content/docs/guide/latex.fa.md b/exampleSite/content/docs/guide/latex.fa.md
index ce5c726..50b9183 100644
--- a/exampleSite/content/docs/guide/latex.fa.md
+++ b/exampleSite/content/docs/guide/latex.fa.md
@@ -1,22 +1,10 @@
 ---
 title: "LaTeX"
 weight: 4
-math: true
 ---
 
-\(\KaTeX\) برای رندر کردن عبارت‌های ریاضی LaTeX استفاده می‌شود. می‌توان آن را در هر صفحه با تنظیم `math` روی `true` در قسمت بالای صفحه فعال کرد.
-
-<!--more-->
-
-```yaml {filename="Markdown"}
----
-title: "صفحه من با LaTeX"
-math: true
----
-
-```
-
-وقتی فعال باشد، اسکریپت‌ها، شیوه‌نامه‌ها و فونت‌های KaTeX به طور خودکار در سایت شما قرار می‌گیرند. می‌توانید از عبارت‌های ریاضی LaTeX در محتوای مارک‌داون خود استفاده کنید.
+به طور پیش‌فرض، \(\KaTeX\) برای رندر کردن عبارت‌های ریاضی LaTeX استفاده می‌شود.
+نیازی به فعال‌سازی دستی نیست، می‌توانید فوراً از عبارت‌های ریاضی LaTeX در محتوای مارک‌داون خود استفاده کنید.
 
 ## مثال
 
@@ -40,6 +28,46 @@ $$F(\omega) = \int_{-\infty}^{\infty} f(t) e^{-j\omega t} \, dt$$
 
 $$F(\omega) = \int_{-\infty}^{\infty} f(t) e^{-j\omega t} \, dt$$
 
+به عنوان مثال، استفاده از محیط هم‌ترازی:
+
+```latex {filename="page.md"}
+$$
+\begin{aligned}
+  \nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \\
+  \nabla \cdot \mathbf{B} &= 0 \\
+  \nabla \times \mathbf{E} &= -\frac{\partial \mathbf{B}}{\partial t} \\
+  \nabla \times \mathbf{B} &= \mu_0 \left( \mathbf{J} + \varepsilon_0 \frac{\partial \mathbf{E}}{\partial t} \right)
+\end{aligned}
+$$
+```
+
+به صورت زیر رندر خواهد شد:
+
+$$
+\begin{aligned}
+  \nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \\
+  \nabla \cdot \mathbf{B} &= 0 \\
+  \nabla \times \mathbf{E} &= -\frac{\partial \mathbf{B}}{\partial t} \\
+  \nabla \times \mathbf{B} &= \mu_0 \left( \mathbf{J} + \varepsilon_0 \frac{\partial \mathbf{E}}{\partial t} \right)
+\end{aligned}
+$$
+
+
+## پیکربندی
+
+> [!IMPORTANT]
+> لطفاً [افزونه passthrough](https://gohugo.io/content-management/mathematics/) را در فایل پیکربندی Hugo فعال و پیکربندی کنید تا Hugo بتواند عبارت‌های ریاضی LaTeX را در محتوای مارک‌داون شما تشخیص دهد.
+
+```yaml {filename="hugo.yaml"}
+markup:
+  goldmark:
+    extensions:
+      passthrough:
+        delimiters:
+          block: [['\[', '\]'], ["$$", "$$"]]
+          inline: [['\(', '\)']]
+        enable: true
+```
 
 ## توابع پشتیبانی شده
 
@@ -57,4 +85,25 @@ $$F(\omega) = \int_{-\infty}^{\infty} f(t) e^{-j\omega t} \, dt$$
 $$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
 ```
 
+به صورت زیر رندر خواهد شد:
+
 $$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
+
+
+## موتور ریاضی
+
+### MathJax
+
+به طور پیش‌فرض، [KaTeX][katex] برای رندر کردن عبارت‌های ریاضی LaTeX در طول فرآیند ساخت استفاده می‌شود که روش ترجیحی است.
+به عنوان جایگزین، می‌توانید از [MathJax][mathjax] برای رندر کردن عبارت‌های ریاضی استفاده کنید.
+
+برای استفاده از آن، موارد زیر را به فایل پیکربندی `hugo.yaml` اضافه کنید:
+
+```yaml {filename="hugo.yaml"}
+params:
+  math:
+    engine: mathjax
+```
+
+[katex]: https://katex.org/
+[mathjax]: https://www.mathjax.org/
diff --git a/exampleSite/content/docs/guide/latex.ja.md b/exampleSite/content/docs/guide/latex.ja.md
index bb179c7..fd86e24 100644
--- a/exampleSite/content/docs/guide/latex.ja.md
+++ b/exampleSite/content/docs/guide/latex.ja.md
@@ -1,22 +1,10 @@
 ---
 title: "LaTeX"
 weight: 4
-math: true
 ---
 
-\(\KaTeX\) は LaTeX の数式をレンダリングするために使用されます。ページのフロントマターで `math` を `true` に設定することで、ページごとに有効にすることができます。
-
-<!--more-->
-
-```yaml {filename="page.md"}
----
-title: "LaTeX を使用した私のページ"
-math: true
----
-
-```
-
-有効にすると、KaTeX のスクリプト、スタイルシート、フォントが自動的にサイトに含まれます。Markdown コンテンツ内で LaTeX 数式を使用できます。
+デフォルトでは、\(\KaTeX\) が LaTeX 数式のレンダリングに使用されます。
+手動での有効化は不要で、Markdown コンテンツで LaTeX 数式をすぐに使い始めることができます。
 
 ## 例
 
@@ -40,20 +28,6 @@ $$F(\omega) = \int_{-\infty}^{\infty} f(t) e^{-j\omega t} \, dt$$
 
 $$F(\omega) = \int_{-\infty}^{\infty} f(t) e^{-j\omega t} \, dt$$
 
-> [!IMPORTANT]
-> Hugo 設定ファイルで [パススルー拡張機能](https://gohugo.io/content-management/mathematics/) を有効にして設定してください。これにより、複雑な式のレンダリング問題を回避するために、デリミタ内の生のコンテンツが保持されます。
-
-```yaml {filename="hugo.yaml"}
-markup:
-  goldmark:
-    extensions:
-      passthrough:
-        delimiters:
-          block: [['\[', '\]'], ['$$', '$$']]
-          inline: [['\(', '\)']]
-        enable: true
-```
-
 例えば、aligned 環境を使用する場合:
 
 ```latex {filename="page.md"}
@@ -78,6 +52,23 @@ $$
 \end{aligned}
 $$
 
+
+## 設定
+
+> [!IMPORTANT]
+> Hugo が Markdown コンテンツ内の LaTeX 数式を検出できるように、Hugo 設定ファイルで [パススルー拡張機能](https://gohugo.io/content-management/mathematics/) を有効にして設定してください。
+
+```yaml {filename="hugo.yaml"}
+markup:
+  goldmark:
+    extensions:
+      passthrough:
+        delimiters:
+          block: [['\[', '\]'], ["$$", "$$"]]
+          inline: [['\(', '\)']]
+        enable: true
+```
+
 ## サポートされている関数
 
 サポートされている関数の一覧については、[KaTeX サポートされている関数](https://katex.org/docs/supported.html) を参照してください。
@@ -94,4 +85,25 @@ $$
 $$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
 ```
 
-$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
\ No newline at end of file
+次のようにレンダリングされます:
+
+$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
+
+
+## 数式エンジン
+
+### MathJax
+
+デフォルトでは、ビルドプロセス中に LaTeX 数式をレンダリングするために [KaTeX][katex] が使用されます（推奨）。
+代替として、[MathJax][mathjax] を使用して数式をレンダリングすることもできます。
+
+MathJax を使用するには、`hugo.yaml` 設定ファイルに以下を追加してください:
+
+```yaml {filename="hugo.yaml"}
+params:
+  math:
+    engine: mathjax
+```
+
+[katex]: https://katex.org/
+[mathjax]: https://www.mathjax.org/
diff --git a/exampleSite/content/docs/guide/latex.md b/exampleSite/content/docs/guide/latex.md
index 20ac9d8..849d719 100644
--- a/exampleSite/content/docs/guide/latex.md
+++ b/exampleSite/content/docs/guide/latex.md
@@ -1,9 +1,10 @@
 ---
 title: "LaTeX"
 weight: 4
-math: true
 ---
-\(\KaTeX\) is used for rendering LaTeX math expressions. No manual activation is needed, you can start using LaTeX math expressions in your Markdown content right away.
+
+By default, \(\KaTeX\) is used for rendering LaTeX math expressions.
+No manual activation is needed, you can start using LaTeX math expressions in your Markdown content right away.
 
 ## Example
 
@@ -15,7 +16,7 @@ Both inline and separate paragraph LaTeX math expressions are supported in the M
 This \(\sigma(z) = \frac{1}{1 + e^{-z}}\) is inline.
 ```
 
-This \(\sigma(z) = \frac{1}{1 + e^{-z}}\) is inline.
+This \( \sigma(z) = \frac{1}{1 + e^{-z}} \) is inline.
 
 ### Separate Paragraph
 
@@ -25,21 +26,7 @@ $$F(\omega) = \int_{-\infty}^{\infty} f(t) e^{-j\omega t} \, dt$$
 
 will be rendered as:
 
-$$F(\omega) = \int_{-\infty}^{\infty} f(t) e^{-j\omega t} \, dt$$
-
-> [!IMPORTANT]
-> Please enable and configure the [passthrough extension](https://gohugo.io/content-management/mathematics/) in the Hugo configuration file. It preserves raw content within the delimiters to avoid rendering issues for complex expressions.
-
-```yaml {filename="hugo.yaml"}
-markup:
-  goldmark:
-    extensions:
-      passthrough:
-        delimiters:
-          block: [['\[', '\]'], ['$$', '$$']]
-          inline: [['\(', '\)']]
-        enable: true
-```
+$$F(\omega) = \int\_{-\infty}^{\infty} f(t) e^{-j\omega t} \, dt$$
 
 For example, using the aligned environment:
 
@@ -65,6 +52,23 @@ $$
 \end{aligned}
 $$
 
+
+## Configuration
+
+> [!IMPORTANT]
+> Please enable and configure the [passthrough extension](https://gohugo.io/content-management/mathematics/) in the Hugo configuration file, so that Hugo can detect LaTeX math expressions in your Markdown content.
+
+```yaml {filename="hugo.yaml"}
+markup:
+  goldmark:
+    extensions:
+      passthrough:
+        delimiters:
+          block: [['\[', '\]'], ["$$", "$$"]]
+          inline: [['\(', '\)']]
+        enable: true
+```
+
 ## Supported Functions
 
 For a list of supported functions, see [KaTeX supported functions](https://katex.org/docs/supported.html).
@@ -81,4 +85,25 @@ Separate paragraph:
 $$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
 ```
 
+will be rendered as:
+
 $$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
+
+
+## Math Engine
+
+### MathJax
+
+By default, [KaTeX][katex] is used for rendering LaTeX math expressions during the build process, which is preferred.
+Alternatively, you can use [MathJax][mathjax] to render math expressions.
+
+To use it instead, add the following to the configuration `hugo.yaml` file:
+
+```yaml {filename="hugo.yaml"}
+params:
+  math:
+    engine: mathjax
+```
+
+[katex]: https://katex.org/
+[mathjax]: https://www.mathjax.org/
diff --git a/exampleSite/content/docs/guide/latex.zh-cn.md b/exampleSite/content/docs/guide/latex.zh-cn.md
index 8300cfe..057ccc9 100644
--- a/exampleSite/content/docs/guide/latex.zh-cn.md
+++ b/exampleSite/content/docs/guide/latex.zh-cn.md
@@ -4,19 +4,8 @@ weight: 4
 math: true
 ---
 
-\(\KaTeX\) 用于渲染 LaTeX 数学表达式。可以通过在页面前置设置中将 `math` 设置为 `true` 来启用它。
-
-<!--more-->
-
-```yaml {filename="page.md"}
----
-title: "我的页面包含 LaTeX"
-math: true
----
-
-```
-
-启用后，KaTeX 的脚本、样式表和字体将自动包含在您的站点中。您可以在 Markdown 内容中开始使用 LaTeX 数学表达式。
+默认情况下，\(\KaTeX\) 用于渲染 LaTeX 数学表达式。
+无需手动激活，您可以直接在 Markdown 内容中开始使用 LaTeX 数学表达式。
 
 ## 示例
 
@@ -40,20 +29,6 @@ $$F(\omega) = \int_{-\infty}^{\infty} f(t) e^{-j\omega t} \, dt$$
 
 $$F(\omega) = \int_{-\infty}^{\infty} f(t) e^{-j\omega t} \, dt$$
 
-> [!IMPORTANT]
-> 请在 Hugo 配置文件中启用并配置 [passthrough 扩展](https://gohugo.io/content-management/mathematics/)。它保留分隔符内的原始内容，以避免复杂表达式的渲染问题。
-
-```yaml {filename="hugo.yaml"}
-markup:
-  goldmark:
-    extensions:
-      passthrough:
-        delimiters:
-          block: [['\[', '\]'], ['$$', '$$']]
-          inline: [['\(', '\)']]
-        enable: true
-```
-
 例如，使用对齐环境：
 
 ```latex {filename="page.md"}
@@ -78,6 +53,23 @@ $$
 \end{aligned}
 $$
 
+
+## 配置
+
+> [!IMPORTANT]
+> 请在 Hugo 配置文件中启用并配置 [passthrough 扩展](https://gohugo.io/content-management/mathematics/)，以便 Hugo 可以检测 Markdown 内容中的 LaTeX 数学表达式。
+
+```yaml {filename="hugo.yaml"}
+markup:
+  goldmark:
+    extensions:
+      passthrough:
+        delimiters:
+          block: [['\[', '\]'], ["$$", "$$"]]
+          inline: [['\(', '\)']]
+        enable: true
+```
+
 ## 支持的函数
 
 有关支持的函数列表，请参阅 [KaTeX 支持的函数](https://katex.org/docs/supported.html)。
@@ -94,4 +86,25 @@ $$
 $$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
 ```
 
+将渲染为：
+
 $$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
+
+
+## 数学引擎
+
+### MathJax
+
+默认情况下，使用 [KaTeX][katex] 在构建过程中渲染 LaTeX 数学表达式，这是首选方式。
+或者，您可以使用 [MathJax][mathjax] 来渲染数学表达式。
+
+要使用 MathJax，请将以下内容添加到 `hugo.yaml` 配置文件中：
+
+```yaml {filename="hugo.yaml"}
+params:
+  math:
+    engine: mathjax
+```
+
+[katex]: https://katex.org/
+[mathjax]: https://www.mathjax.org/
diff --git a/exampleSite/hugo.yaml b/exampleSite/hugo.yaml
index 596de75..453dc90 100644
--- a/exampleSite/hugo.yaml
+++ b/exampleSite/hugo.yaml
@@ -58,7 +58,7 @@ markup:
     extensions:
       passthrough:
         delimiters:
-          block: [['\[', '\]'], ["$$", "$$"]]
+          block: [['\[', '\]'], ['$$', '$$']]
           inline: [['\(', '\)']]
         enable: true
 
diff --git a/layouts/_markup/render-passthrough.html b/layouts/_markup/render-passthrough.html
index 0ed0011..3c23c6a 100644
--- a/layouts/_markup/render-passthrough.html
+++ b/layouts/_markup/render-passthrough.html
@@ -1,9 +1,20 @@
-{{- $opts := dict "output" "htmlAndMathml" "displayMode" (eq .Type "block") }}
-{{- with try (transform.ToMath .Inner $opts) }}
-  {{- with .Err }}
-    {{ errorf "Unable to render mathematical markup to HTML using the transform.ToMath function. The KaTeX display engine threw the following error: %s: see %s." . $.Position }}
-  {{- else }}
-    {{- .Value }}
-    {{- $.Page.Store.Set "hasMath" true }}
+{{- $engine := site.Params.math.engine | default "katex" -}}
+{{- if eq $engine "katex" -}}
+  {{- $opts := dict "output" "htmlAndMathml" "displayMode" (eq .Type "block") }}
+  {{- with try (transform.ToMath .Inner $opts) }}
+    {{- with .Err }}
+      {{ errorf "Unable to render mathematical markup to HTML using the transform.ToMath function. The KaTeX display engine threw the following error: %s: see %s." . $.Position }}
+    {{- else }}
+      {{- .Value }}
+      {{- $.Page.Store.Set "hasMath" true }}
+    {{- end }}
   {{- end }}
+{{- else -}}
+  {{/* MathJax - need to add delimiters back in */}}
+  {{- $.Page.Store.Set "hasMath" true }}
+  {{- if eq .Type "block" -}}
+    \[{{- .Inner -}}\]
+  {{- else -}}
+    \( {{- .Inner -}} \)
+  {{- end -}}
 {{- end -}}
diff --git a/layouts/_partials/head.html b/layouts/_partials/head.html
index 220b965..0848533 100644
--- a/layouts/_partials/head.html
+++ b/layouts/_partials/head.html
@@ -85,7 +85,8 @@
 
   <!-- KaTeX-->
   {{ $noop := .WordCount -}}
-  {{ if .Page.Store.Get "hasMath" -}}
+  {{- $engine := site.Params.math.engine | default "katex" -}}
+  {{ if and (.Page.Store.Get "hasMath") (eq $engine "katex") -}}
     <!-- TODO: make url configurable -->
     {{ $katexBaseUrl := "https://cdn.jsdelivr.net/npm/katex@latest/dist" }}
     {{ $katexCssUrl := printf "%s/katex%s.css" $katexBaseUrl (cond hugo.IsProduction ".min" "") -}}
@@ -103,6 +104,8 @@
         {{ end -}}
       {{ end -}}
     {{ end -}}
+  {{ else if and (.Page.Store.Get "hasMath") (eq $engine "mathjax") -}}
+    {{ partialCached "scripts/mathjax.html" . -}}
   {{ end -}}
 
   {{ partial "custom/head-end.html" . -}}
diff --git a/layouts/_partials/scripts/mathjax.html b/layouts/_partials/scripts/mathjax.html
new file mode 100644
index 0000000..cc129af
--- /dev/null
+++ b/layouts/_partials/scripts/mathjax.html
@@ -0,0 +1,21 @@
+{{/* MathJax */}}
+{{ $mathjaxVersion := site.Params.math.mathjaxVersion | default "3" -}}
+{{ $mathjaxJsUrl := printf "https://cdn.jsdelivr.net/npm/mathjax@%s/es5/tex-chtml.js" $mathjaxVersion -}}
+<script defer id="MathJax-script" src="{{ $mathjaxJsUrl }}" crossorigin="anonymous" async></script>
+<script>
+  MathJax = {
+    loader: {
+      load: ["ui/safe"],
+    },
+    tex: {
+      displayMath: [
+        ["\\[", "\\]"],
+        ["$$", "$$"],
+      ],
+      inlineMath: [
+        ["\\(", "\\)"],
+        ["$", "$"],
+      ],
+    },
+  };
+</script>
diff --git a/layouts/_partials/tags.html b/layouts/_partials/tags.html
index d67ed91..291a9ea 100644
--- a/layouts/_partials/tags.html
+++ b/layouts/_partials/tags.html
@@ -1,7 +1,7 @@
 <p class="hx:opacity-50 hx:text-sm hx:leading-7">
-{{- range $tag := .Params.tags -}}
-  {{- with $.Site.GetPage (printf "/tags/%s" $tag) -}}
-    <a class="hx:inline-block hx:mr-2" href="{{ .RelPermalink }}">#{{ .Title }}</a>
+  {{- range $tag := .Params.tags -}}
+    {{- with $.Site.GetPage (printf "/tags/%s" $tag) -}}
+      <a class="hx:inline-block hx:mr-2" href="{{ .RelPermalink }}">#{{ .Title }}</a>
+    {{- end -}}
   {{- end -}}
-{{- end -}}
-</p>
\ No newline at end of file
+</p>