Merge branch '23-fix-mathjax-rendering-issues-with-instant-navigation' into release

Author: steven-varga

docs/javascripts/mathjax.js

@@ -1,31 +1,33 @@
-// Load this BEFORE the MathJax CDN script in mkdocs.yml
+// MathJax v3 configuration for MkDocs Material
+// Place this file BEFORE the MathJax CDN script in mkdocs.yml
+
 window.MathJax = {
   tex: {
-    // include the delimiters you actually use:
-    inlineMath: [['\\(', '\\)'], ['$', '$']],
-    displayMath: [['\\[', '\\]'], ['$$', '$$']],
+    inlineMath: [['\\(', '\\)'], ['$', '$']],    // inline math
+    displayMath: [['\\[', '\\]'], ['$$', '$$']], // display math
     processEscapes: true,
     processEnvironments: true
   },
   options: {
-    // With arithmatex(generic:true), content is wrapped in .arithmatex
-    processHtmlClass: 'arithmatex',
-    ignoreHtmlClass: '.*'   // process only .arithmatex
+    processHtmlClass: 'arithmatex', // only process .arithmatex spans
+    ignoreHtmlClass: '.*'
   },
   startup: {
-    // we'll control typesetting manually to avoid races
-    typeset: false
+    typeset: false // disable auto-typeset; we'll call it ourselves
   }
 };
 
-// Re-typeset after every MkDocs Material page swap
+// Hook into MkDocs Material instant navigation
 if (window.document$) {
   document$.subscribe(() => {
-    const container = document.querySelector('.md-content'); // main article
-    // Defer to next animation frame so DOM is fully replaced
-    requestAnimationFrame(() => {
-      MathJax.typesetClear();                      // clear previous MathItems
-      MathJax.typesetPromise([container]);         // typeset current page
-    });
+    const container = document.querySelector('.md-content');
+    if (window.MathJax) {
+      // Ensure MathJax has finished startup before typesetting
+      MathJax.startup.promise
+        .then(() => MathJax.typesetPromise([container]))
+        .catch(err =>
+          console.error("MathJax typeset failed: " + err.message)
+        );
+    }
   });
 }

mkdocs.yml

@@ -49,7 +49,6 @@ plugins:
 theme:
   name: material
   custom_dir: docs/overrides
-  highlightjs: true
   features:
     #- navigation.instant #<- messes up mathjax, keep it disabled!
     - search.suggest
@@ -80,10 +79,7 @@ extra:
       link: https://www.linkedin.com/in/steven-varga-04224a19/
     - icon: material/github 
       link: https://github.com/vargaconsulting
-  icons:
-    - material
-    - fontawesome/brands
-    - fontawesome/solid
+
   analytics:
     provider: google
     property: G-L58Z6SZ3TN
@@ -106,7 +102,6 @@ markdown_extensions:
       generic: true
   - pymdownx.details
   - pymdownx.superfences
-  - pymdownx.snippets
   - pymdownx.blocks.caption
   - pymdownx.caret
   - pymdownx.mark
@@ -123,10 +118,10 @@ markdown_extensions:
         - docs/blog/scripts
 
 extra_javascript:
+  - javascripts/mathjax.js
   - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
   - https://cdn.tailwindcss.com 
   - javascripts/tw-config.js   
-  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
   - https://cdn.jsdelivr.net/npm/asciinema-player@3.0.1/dist/bundle/asciinema-player.js
   - https://unpkg.com/alpinejs@3.14.9/dist/cdn.min.js
   - https://unpkg.com/@popperjs/core@2