KaTeX +Mermaid (#126)

* Add KaTeX support for math rendering in documentation

Introduced web_extras/katex.js and updated build scripts to copy it to the appropriate assets directories. Updated mkdocs.yml to include KaTeX CSS/JS and enabled pymdownx.arithmatex extension for math rendering. This enables LaTeX-style math support in the documentation.

* Add mermaid

Configured pymdownx.superfences in mkdocs.yml to support custom 'mermaid' code fences, enabling better integration of mermaid diagrams in documentation.

build.ps1

@@ -98,6 +98,10 @@ if (Test-Path "web_extras\icon-theme.js") {
     Copy-Item "web_extras\icon-theme.js" "docs/assets/javascripts/icon-theme.js" -Force
 }
 
+if (Test-Path "web_extras\katex.js") {
+    Copy-Item "web_extras\katex.js" "docs/assets/javascripts/katex.js" -Force
+}
+
 Write-Host "Converting GitHub image URLs to local paths..."
 
 if ($DownloadSvg) {
@@ -256,6 +260,13 @@ if (Test-Path "web_extras\icon-theme.js") {
     Write-Host "Warning: web_extras\icon-theme.js not found - skipping" -ForegroundColor Yellow
 }
 
+if (Test-Path "web_extras\katex.js") {
+    Copy-Item "web_extras\katex.js" "wiki\assets\javascripts\katex.js" -Force
+    Write-Host "Copied katex.js"
+} else {
+    Write-Host "Warning: web_extras\katex.js not found - skipping" -ForegroundColor Yellow
+}
+
 if (Test-Path "web_extras") {
     New-Item -ItemType Directory -Path "wiki\web_extras" -Force | Out-Null
     Copy-Item -Path "web_extras\*" -Destination "wiki\web_extras" -Recurse -Force -ErrorAction SilentlyContinue

build.sh

@@ -134,6 +134,7 @@ done
 mkdir -p docs/assets/stylesheets docs/assets/javascripts
 [ -f "web_extras/extra.css" ] && cp "web_extras/extra.css" docs/assets/stylesheets/extra.css
 [ -f "web_extras/icon-theme.js" ] && cp "web_extras/icon-theme.js" docs/assets/javascripts/icon-theme.js
+[ -f "web_extras/katex.js" ] && cp "web_extras/katex.js" docs/assets/javascripts/katex.js
 
 # Build mkdocs and output to wiki folder
 mkdocs build --site-dir wiki
@@ -227,6 +228,12 @@ else
   echo "Warning: web_extras/icon-theme.js not found - skipping"
 fi
 
+if [ -f "web_extras/katex.js" ]; then
+  cp "web_extras/katex.js" wiki/assets/javascripts/katex.js
+else
+  echo "Warning: web_extras/katex.js not found - skipping"
+fi
+
 if [ -d "web_extras" ]; then
   mkdir -p wiki/web_extras
   cp -r web_extras/* wiki/web_extras/ 2>/dev/null || true

mkdocs.yml

@@ -37,8 +37,12 @@ theme:
 
 extra_css:
   - assets/stylesheets/extra.css
+  - https://unpkg.com/katex@0/dist/katex.min.css
 
 extra_javascript:
+  - https://unpkg.com/katex@0/dist/katex.min.js
+  - https://unpkg.com/katex@0/dist/contrib/auto-render.min.js
+  - assets/javascripts/katex.js
   - assets/javascripts/icon-theme.js
 
 plugins:
@@ -61,7 +65,13 @@ markdown_extensions:
   - md_in_html
   - admonition
   - pymdownx.details  # For collapsible admonitions
-  - pymdownx.superfences
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.arithmatex:
+      generic: true
 
 extra:
   generator: false # hides "Made with Material for MkDocs" from footer

web_extras/katex.js

@@ -0,0 +1,16 @@
+if (typeof document$ !== 'undefined' && document$.subscribe) {
+  document$.subscribe(({ body }) => {
+    if (typeof renderMathInElement !== 'function') {
+      return;
+    }
+
+    renderMathInElement(body, {
+      delimiters: [
+        { left: '$$', right: '$$', display: true },
+        { left: '$', right: '$', display: false },
+        { left: '\\(', right: '\\)', display: false },
+        { left: '\\[', right: '\\]', display: true },
+      ],
+    });
+  });
+}