Add math directive (#2090)

* Add math directive

* Prettify

* Fix linter issue

* Formatting

* Title of doc

Author: theletterf

docs/_docset.yml

@@ -102,6 +102,7 @@ toc:
       - file: icons.md
       - file: images.md
       - file: kbd.md
+      - file: math.md
       - file: lists.md
       - file: line_breaks.md
       - file: links.md

docs/syntax/directives.md

@@ -10,19 +10,67 @@ import { initTabs } from './tabs'
 import { initTocNav } from './toc-nav'
 import 'htmx-ext-head-support'
 import 'htmx-ext-preload'
+import katex from 'katex'
+import 'katex/dist/katex.min.css'
 import { $, $$ } from 'select-dom'
 import { UAParser } from 'ua-parser-js'
 
 const { getOS } = new UAParser()
 const isLazyLoadNavigationEnabled =
     $('meta[property="docs:feature:lazy-load-navigation"]')?.content === 'true'
 
+/**
+ * Initialize KaTeX math rendering for elements with class 'math'
+ */
+function initMath() {
+    const mathElements = $$('.math')
+    mathElements.forEach((element) => {
+        try {
+            const content = element.textContent?.trim()
+            if (!content) return
+
+            // Determine if this is display math based on content and element type
+            const isDisplayMath =
+                element.tagName === 'DIV' ||
+                content.includes('\\[') ||
+                content.includes('$$') ||
+                content.includes('\\begin{') ||
+                content.includes('\n')
+
+            // Clean up common LaTeX delimiters
+            const cleanContent = content
+                .replace(/^\$\$|\$\$$/g, '') // Remove $$ delimiters
+                .replace(/^\\\[|\\\]$/g, '') // Remove \[ \] delimiters
+                .trim()
+
+            // Clear the element content before rendering
+            element.innerHTML = ''
+
+            katex.render(cleanContent, element, {
+                throwOnError: false,
+                displayMode: isDisplayMath,
+                strict: false, // Allow some LaTeX extensions
+                trust: false, // Security: don't trust arbitrary commands
+                output: 'mathml', // Only render MathML, not HTML
+                macros: {
+                    // Add common macros if needed
+                },
+            })
+        } catch (error) {
+            console.warn('KaTeX rendering error:', error)
+            // Fallback: keep the original content
+            element.innerHTML = element.textContent || ''
+        }
+    })
+}
+
 document.addEventListener('htmx:load', function (event) {
     initTocNav()
     initHighlight()
     initCopyButton()
     initTabs()
     initAppliesSwitch()
+    initMath()
 
     // We do this so that the navigation is not initialized twice
     if (isLazyLoadNavigationEnabled) {

docs/syntax/math.md

@@ -224,3 +224,7 @@ body {
 	user-select: none;
 	pointer-events: none;
 }
+
+math {
+	margin-top: 1.5rem;
+}