feat(math): support local katex assets and improve docs (#742)

* refactor(math): update LaTeX guide and enhance KaTeX integration

- Revised the LaTeX documentation for clarity and improved structure, changing section titles and descriptions for better understanding.
- Added support for chemistry expressions using the mhchem extension.
- Introduced a new KaTeX CSS loader partial to streamline the integration of KaTeX, allowing for configurable remote or local asset loading.
- Updated the head partial to utilize the new KaTeX loader, enhancing the flexibility of math rendering options.

* refactor(mathjax): simplify MathJax script URL configuration

- Removed the dynamic version assignment for MathJax and set a fixed version in the script URL for consistency and clarity.

* docs(latex): enhance LaTeX guide and clarify chemistry expressions

- Updated section titles for better clarity, changing "Supported Functions" to "Chemistry Expressions."
- Improved description of the mhchem extension for rendering chemistry equations.
- Removed redundant instructions regarding the passthrough extension in Hugo.
- Corrected minor typographical errors in references to MathJax.

layouts/_partials/head.html

@@ -83,27 +83,11 @@
     }
   </script>
 
-  <!-- KaTeX-->
+  <!-- Math engine -->
   {{ $noop := .WordCount -}}
   {{- $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" "") -}}
-    {{ $katexFontPattern := "url(fonts/" }}
-    {{ $katexFontSubstituted := printf "url(%s/fonts/" $katexBaseUrl }}
-
-    {{ with try (resources.GetRemote $katexCssUrl) -}}
-      {{ with .Err -}}
-        {{ errorf "Could not retrieve KaTeX css file from %s. Reason: %s." $katexCssUrl . -}}
-      {{ else with .Value -}}
-        {{ $katexCssContent := strings.Replace .Content $katexFontPattern $katexFontSubstituted }}
-        {{ with resources.FromString (printf "css/katex%s.css" (cond hugo.IsProduction ".min" "")) $katexCssContent -}}
-          {{ $cssHash := . | fingerprint "sha512" -}}
-          <link rel="stylesheet" href="{{- .RelPermalink -}}" integrity="{{- $cssHash.Data.Integrity -}}" crossorigin="anonymous" />
-        {{ end -}}
-      {{ end -}}
-    {{ end -}}
+    {{ partialCached "scripts/katex.html" . -}}
   {{ else if and (.Page.Store.Get "hasMath") (eq $engine "mathjax") -}}
     {{ partialCached "scripts/mathjax.html" . -}}
   {{ end -}}

layouts/_partials/scripts/katex.html

@@ -0,0 +1,88 @@
+{{- /* KaTeX CSS loader
+
+  Behavior (driven by site.params.math.katex):
+  - base (remote URL) + optional css:
+    - Construct remote CSS URL: "{{ base }}/{{ css | default "katex[.min].css" }}".
+    - Fetch via resources.GetRemote, rewrite font URLs to "{{ base }}/fonts/...".
+    - Build and fingerprint; emit <link rel="stylesheet" integrity>.
+  - base (local path or not set) + css (asset path):
+    - Read CSS from Hugo assets via resources.Get; DO NOT rewrite font URLs.
+    - Build and fingerprint; emit <link rel="stylesheet" integrity>.
+  - base (local path) only (no css):
+    - Link directly to "{{ base }}/katex[.min].css" (no processing).
+  - Nothing set:
+    - Default to CDN latest base; same as remote path above.
+
+  Additional:
+  - assets: optional list to publish extra assets. CSS/JS get tags with integrity (JS loads async).
+*/ -}}
+{{- $noop := .WordCount -}}
+
+{{- $katexBase := "https://cdn.jsdelivr.net/npm/katex@latest/dist" -}}
+{{- with site.Params.math.katex.base -}}
+  {{- $katexBase = . -}}
+{{- end -}}
+
+{{- $katexCssAsset := "" -}}
+{{- with site.Params.math.katex.css -}}
+  {{- $katexCssAsset = . -}}
+{{- end -}}
+
+{{- $s := newScratch -}}
+{{- $isRemoteBase := or (strings.HasPrefix $katexBase "http://") (strings.HasPrefix $katexBase "https://") -}}
+
+{{- /* CSS retrieval consolidated: get raw CSS from either local asset or remote, then process once */ -}}
+{{- $minSuffix := cond hugo.IsProduction ".min" "" -}}
+{{- if $isRemoteBase -}}
+  {{- $cssPath := cond (ne $katexCssAsset "") $katexCssAsset (printf "katex%s.css" $minSuffix) -}}
+  {{- $katexCssUrl := printf "%s/%s" $katexBase $cssPath -}}
+  {{- with try (resources.GetRemote $katexCssUrl) -}}
+    {{- with .Err -}}
+      {{- errorf "Could not retrieve KaTeX css file from %s. Reason: %s." $katexCssUrl . -}}
+    {{- else with .Value -}}
+      {{- $s.Set "katexCssValue" .Content -}}
+    {{- end -}}
+  {{- end -}}
+{{- else if $katexCssAsset -}}
+  {{- with resources.Get $katexCssAsset -}}
+    {{- $s.Set "katexCssValue" .Content -}}
+  {{- else -}}
+    {{- errorf "KaTeX css asset not found at %q" $katexCssAsset -}}
+  {{- end -}}
+{{- end -}}
+
+{{- with $s.Get "katexCssValue" -}}
+  {{- $cssContent := . -}}
+  {{- if $isRemoteBase -}}
+    {{- $fontPattern := "url(fonts/" -}}
+    {{- $fontSub := printf "url(%s/fonts/" $katexBase -}}
+    {{- $cssContent = strings.Replace $cssContent $fontPattern $fontSub -}}
+  {{- end -}}
+  {{- with resources.FromString (printf "css/katex%s.css" $minSuffix) $cssContent -}}
+    {{- $css := . | fingerprint "sha512" -}}
+    <link rel="stylesheet" href="{{ $css.RelPermalink }}" integrity="{{ $css.Data.Integrity }}" />
+  {{- end -}}
+{{- else -}}
+  {{- if not $isRemoteBase -}}
+    {{- $cssPath := cond (ne $katexCssAsset "") $katexCssAsset (printf "katex%s.css" $minSuffix) -}}
+    <link rel="stylesheet" href="{{ printf "%s/%s" $katexBase $cssPath }}" />
+  {{- end -}}
+{{- end -}}
+
+{{- /* Optionally publish files (fonts, css, js, etc.) from assets and emit tags for css/js with integrity and crossorigin */ -}}
+{{- with site.Params.math.katex.assets -}}
+  {{- range . -}}
+    {{- with resources.Get . -}}
+      {{- $name := .Name | lower -}}
+      {{- if strings.HasSuffix $name ".css" -}}
+        {{- $built := . | fingerprint "sha512" -}}
+        <link rel="stylesheet" href="{{ $built.RelPermalink }}" integrity="{{ $built.Data.Integrity }}" crossorigin="anonymous" />
+      {{- else if or (strings.HasSuffix $name ".js") (strings.HasSuffix $name ".mjs") -}}
+        {{- $built := . | fingerprint "sha512" -}}
+        <script src="{{ $built.RelPermalink }}" async integrity="{{ $built.Data.Integrity }}" crossorigin="anonymous"></script>
+      {{- else -}}
+        {{- .Publish -}}
+      {{- end -}}
+    {{- end -}}
+  {{- end -}}
+{{- end -}}

layouts/_partials/scripts/mathjax.html

@@ -1,6 +1,5 @@
 {{/* MathJax */}}
-{{ $mathjaxVersion := site.Params.math.mathjaxVersion | default "3" -}}
-{{ $mathjaxJsUrl := printf "https://cdn.jsdelivr.net/npm/mathjax@%s/es5/tex-chtml.js" $mathjaxVersion -}}
+{{ $mathjaxJsUrl := "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js" -}}
 <script defer id="MathJax-script" src="{{ $mathjaxJsUrl }}" crossorigin="anonymous" async></script>
 <script>
   MathJax = {