Allow mathematics in Markdown, retrieve KaTeX scripts files at build …

…time
google · Oct 31, 2024 · 01d94e9 · 01d94e9
1 parent 68aa7b3
commit 01d94e9
Show file tree

Hide file tree

Showing 4 changed files with 80 additions and 31 deletions.
diff --git a/layouts/partials/scripts.html b/layouts/partials/scripts.html
@@ -1,13 +1,5 @@
-{{ $needKaTeX  := or .Site.Params.katex.enable .Params.math .Params.chem -}}
-{{ $needmhchem := or .Site.Params.katex.mhchem.enable .Params.chem -}}
-{{ if ge hugo.Version "0.93.0" -}}
-  {{ $needKaTeX = or $needKaTeX (.Page.Store.Get "hasKaTeX") (.Page.Store.Get "hasmhchem") -}}
-  {{ $needmhchem = or $needmhchem (.Page.Store.Get "hasmhchem") -}}
-{{ else -}}
-  {{ if or $needKaTeX $needmhchem -}}
-    {{ warnf "Outdated Hugo version %s, consider upgrading to make full use of all theme features" hugo.Version  }}
-  {{ end -}}
-{{ end -}}
+{{ $needKaTeX  := or .Params.math .Site.Params.katex.enable .Params.chem .Site.Params.chem (.Page.Store.Get "hasKaTeX") (.Page.Store.Get "hasmhchem") -}}
+{{ $needmhchem := or .Params.chem .Site.Params.katex.mhchem.enable (.Page.Store.Get "hasmhchem") -}}
 
 {{ if .Site.Params.markmap.enable -}}
 <style>
@@ -34,27 +26,8 @@
   <script src='{{ "js/deflate.js" | relURL }}'></script>
 {{ end -}}
 
-{{ if  $needKaTeX -}}
-{{/* load stylesheet and scripts for KaTeX support */ -}}
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.10/dist/katex.min.css"
-      integrity="sha512-r2+FkHzf1u0+SQbZOoIz2RxWOIWfdEzRuYybGjzKq18jG9zaSfEy9s3+jMqG/zPtRor/q4qaUCYQpmSjTw8M+g==" crossorigin="anonymous">
-  {{/* The loading of KaTeX is deferred to speed up page rendering */ -}}
-<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.10/dist/katex.min.js"
-        integrity="sha512-INps9zQ2GUEMCQD7xiZQbGUVnqnzEvlynVy6eqcTcHN4+aQiLo9/uaQqckDpdJ8Zm3M0QBs+Pktg4pz0kEklUg=="
-        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.10/dist/contrib/mhchem.min.js"
-        integrity="sha512-mxjNw/u1lIsFC09k/unscDRY3ofIYPVFbWkP8slrePcS36ht4d/OZ8rRu5yddB2uiqajhTcLD8+jupOWuYPebg=="
-        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.10/dist/contrib/auto-render.min.js"
-       integrity="sha512-YJVxTjqttjsU3cSvaTRqsSl0wbRgZUNF+NGGCgto/MUbIvaLdXQzGTCQu4CvyJZbZctgflVB0PXw9LLmTWm5/w==" 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>
+{{ if $needKaTeX -}}
+  {{ partial "scripts/katex.html" (dict "mhchem" $needmhchem) -}}
 {{ end -}}
 
 {{ $jsBs := resources.Get "vendor/bootstrap/dist/js/bootstrap.bundle.js" -}}

diff --git a/layouts/partials/scripts/katex.html b/layouts/partials/scripts/katex.html
@@ -0,0 +1,48 @@
+{{ $version := .Site.Params.katex.version | default "latest" -}}
+
+{{/* load stylesheet and scripts for KaTeX support */ -}}
+{{ $katex_css_url := printf "https://cdn.jsdelivr.net/npm/katex@%s/dist/katex.min.css" $version -}}
+{{ with resources.GetRemote $katex_css_url -}}
+  {{ with .Err -}}
+    {{ errorf "Could not retrieve KaTeX css file from CDN. Reason: %s." . -}}
+  {{ else -}}
+    {{ $secureCSS := . | resources.Fingerprint "sha512" -}}
+<link rel="stylesheet" href="{{- $katex_css_url -}}" integrity="{{- $secureCSS.Data.Integrity -}}" crossorigin="anonymous">
+  {{ end -}}
+{{ else -}}
+  {{ errorf "Invalid KaTeX version %s, could not retrieve this version from CDN." $version -}}
+{{ end -}}
+
+{{/* The loading of KaTeX is deferred to speed up page rendering */ -}}
+{{ $katex_js_url := printf "https://cdn.jsdelivr.net/npm/katex@%s/dist/katex.min.js" $version -}}
+{{ with resources.GetRemote $katex_js_url -}}
+  {{ with .Err -}}
+    {{ errorf "Could not retrieve KaTeX script from CDN. Reason: %s." . -}}
+  {{ else -}}
+    {{ $secureJS := . | resources.Fingerprint "sha512" -}}
+<script defer src="{{- .RelPermalink -}}" integrity="{{- $secureJS.Data.Integrity -}}" crossorigin="anonymous" ></script>    
+  {{ end -}}
+{{ else -}}
+  {{ errorf "Invalid KaTeX version %s, could not retrieve this version from CDN." $version -}}
+{{ end -}}
+
+{{/* Add support for displaying chemical equations and physical units by loading the mhchem extension: */ -}}
+{{ if .mhchem -}}
+{{ partial "scripts/mhchem.html" (dict "version" $version) -}}
+{{ end -}}
+
+{{/* To automatically render math in text elements, include the auto-render extension: */ -}}
+
+{{ $katex_autorender_url := printf "https://cdn.jsdelivr.net/npm/katex@%s/dist/contrib/auto-render.min.js" $version -}}
+{{ with resources.GetRemote $katex_autorender_url -}}
+  {{ with .Err -}}
+    {{ errorf "Could not retrieve KaTeX auto render extension from CDN. Reason: %s." . -}}
+  {{ else -}}
+    {{ $secureJS := . | resources.Fingerprint "sha512" -}}
+<script defer src="{{- .RelPermalink -}}" integrity="{{- $secureJS.Data.Integrity -}}" 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 -}}
+{{ else -}}
+  {{ errorf "Invalid KaTeX version %s, could not retrieve this version from CDN." $version -}}
+{{ end -}}
diff --git a/layouts/partials/scripts/mhchem.html b/layouts/partials/scripts/mhchem.html
@@ -0,0 +1,12 @@
+{{/* Add support for displaying chemical equations and physical units by loading the mhchem extension: */ -}}
+{{ $mhchem_url := printf "https://cdn.jsdelivr.net/npm/katex@%s/dist/contrib/mhchem.min.js" .version -}}
+{{ with resources.GetRemote $mhchem_url -}}
+  {{ with .Err -}}
+    {{ errorf "Could not retrieve mhchem script from CDN. Reason: %s." . -}}
+  {{ else -}}
+    {{ $secureJS := . | resources.Fingerprint "sha512" -}}
+<script defer src="{{- .RelPermalink -}}" integrity="{{- $secureJS.Data.Integrity -}}" crossorigin="anonymous" ></script>    
+  {{ end -}}
+{{ else -}}
+  {{ errorf "Invalid KaTeX version %s, could not retrieve this version from CDN." .version -}}
+{{ end -}}
diff --git a/userguide/hugo.yaml b/userguide/hugo.yaml
@@ -38,6 +38,18 @@ markup:
     parser:
       attribute:
         block: true
+    extensions:
+      passthrough:
+        enable: true
+        delimiters:
+          block:
+          - - \[
+            - \]
+          - - $$
+            - $$
+          inline:
+          - - \(
+            - \)
     renderer:
       unsafe: true
   highlight:
@@ -120,6 +132,10 @@ params:
     enable: true
   drawio:
     enable: true
+  katex:
+    enable: false
+    mhchem:
+      enable: false
 
 taxonomies:
   tag: tags