Unit 11: math engine — drop MathJax, keep KaTeX (gated, with SRI)

README.md

@@ -139,6 +139,22 @@ Described at [documentation](https://github.com/stradichenko/PKB-theme/blob/main
 ### [Color Theme Customization](https://stradichenko.github.io/PKB-theme/docs/color-theme-customization)
 
 
+### Math support (KaTeX)
+
+Math rendering is powered by [KaTeX](https://katex.org/). To enable math on a page, add `math = true` to its front matter:
+
+```toml
++++
+title = "My math post"
+math = true
++++
+```
+
+Then write inline math with `$...$` or `\(...\)` and display math with `$$...$$` or `\[...\]`. Chemical equations (`mhchem`) are also supported. To enable math site-wide, set `math = true` under `[params]` in your site config; individual pages can still override with `math = false`.
+
+A global `window.reprocessMath()` hook is exposed for re-rendering math after dynamic DOM updates.
+
+
 ## FAQ
 ### Hugo's Theme Configuration Inheritance (Lookup Order)
 

assets/js/katex-init.js

@@ -0,0 +1,43 @@
+// KaTeX initialization
+// Configures auto-render and exposes window.reprocessMath for dynamic content.
+(function () {
+  "use strict";
+
+  var KATEX_OPTIONS = {
+    delimiters: [
+      { left: "$$", right: "$$", display: true },
+      { left: "$", right: "$", display: false },
+      { left: "\\(", right: "\\)", display: false },
+      { left: "\\[", right: "\\]", display: true }
+    ],
+    throwOnError: false,
+    errorColor: "#cc0000",
+    strict: false,
+    trust: true
+  };
+
+  function renderAll(root) {
+    if (typeof window.renderMathInElement !== "function") {
+      return;
+    }
+    try {
+      window.renderMathInElement(root || document.body, KATEX_OPTIONS);
+    } catch (err) {
+      // KaTeX auto-render handles per-formula errors via errorColor; this is a safety net.
+      if (window.console && console.warn) {
+        console.warn("KaTeX render failed:", err && err.message);
+      }
+    }
+  }
+
+  // Expose a global re-render hook for dynamic content (e.g. theme toggles, AJAX inserts).
+  window.reprocessMath = function (root) {
+    renderAll(root);
+  };
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", function () { renderAll(); });
+  } else {
+    renderAll();
+  }
+})();

layouts/_default/baseof.html

@@ -61,11 +61,7 @@
   {{ partial "head.html" . }}
 
   {{ block "head" . }}{{ end }}
-
-  {{ if .Param "math" }}
-    {{ partialCached "math.html" . }}
-  {{ end }}
-
+
   <!-- CSS preload with proper attributes -->
   {{ $mainCSS := resources.Get "css/main.css" }}
   {{ if $mainCSS }}

layouts/partials/head.html

@@ -17,13 +17,14 @@
     <!-- Main Stylesheet -->
     {{ partial "head/styles.html" . }}
 
-    {{/* Math Support - Load early for better rendering */}}
-    {{- if .Params.math -}}
+    {{/* Math Support - Preload KaTeX assets when enabled (page param falls back to site default) */}}
+    {{- $math := .Param "math" -}}
+    {{- if $math -}}
     <!-- KaTeX CSS - Preload for better performance -->
     <link rel="preload" href="https://cdn.jsdelivr.net/npm/katex@0.16.32/dist/katex.min.css" as="style" onload="this.onload=null;this.rel='stylesheet'">
     <noscript><link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.32/dist/katex.min.css"></noscript>
-    
-    <!-- KaTeX JS - Load with high priority -->
+
+    <!-- KaTeX JS - Preload with high priority -->
     <link rel="preload" href="https://cdn.jsdelivr.net/npm/katex@0.16.32/dist/katex.min.js" as="script">
     <link rel="preload" href="https://cdn.jsdelivr.net/npm/katex@0.16.32/dist/contrib/auto-render.min.js" as="script">
     <link rel="preload" href="https://cdn.jsdelivr.net/npm/katex@0.16.32/dist/contrib/mhchem.min.js" as="script">
@@ -58,7 +59,7 @@
     <script src="{{ $scrollbarFadeJS.RelPermalink }}" defer></script>
 
     {{/* Math rendering scripts - Load after DOM is ready */}}
-    {{- if .Params.math -}}
+    {{- if $math -}}
     <!-- KaTeX JS -->
     <script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.32/dist/katex.min.js" integrity="sha384-TNnVz4NqBjFIUtubnHyyCWyGiIboUd7yCCtn7k4DwDnkWWqyOEtNKYEELv0jW+NU" crossorigin="anonymous"></script>
 
@@ -68,22 +69,10 @@
     <!-- KaTeX auto-render extension -->
     <script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.32/dist/contrib/auto-render.min.js" integrity="sha384-JKXHIJf8PKPyDFptuKZoUyMRQJAmQKj4B4xyOca62ebJhciMYGiDdq/9twUUWyZH" crossorigin="anonymous"></script>
 
-    <!-- KaTeX Configuration -->
-    <script>
-    document.addEventListener("DOMContentLoaded", function() {
-        renderMathInElement(document.body, {
-            delimiters: [
-                {left: '$$', right: '$$', display: true},
-                {left: '$', right: '$', display: false},
-                {left: '\\(', right: '\\)', display: false},
-                {left: '\\[', right: '\\]', display: true}
-            ],
-            throwOnError: false,
-            errorColor: '#cc0000',
-            strict: false,
-            trust: true,
-        });
-    });
-    </script>
+    <!-- KaTeX initialization (auto-render + window.reprocessMath hook) -->
+    {{ with resources.Get "js/katex-init.js" }}
+        {{ $katexInit := . | js.Build | minify | fingerprint }}
+        <script src="{{ $katexInit.RelPermalink }}" integrity="{{ $katexInit.Data.Integrity }}" crossorigin="anonymous" defer></script>
+    {{ end }}
     {{- end -}}
 </head>