Add math directive

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

@@ -72,6 +72,7 @@ The following directives are available:
 - [Dropdowns](dropdowns.md) - Collapsible content
 - [Images](images.md) - Enhanced image handling
 - [Include](file_inclusion.md) - Include content from other files
+- [Math](math.md) - Mathematical expressions and equations
 - [Settings](automated_settings.md) - Configuration blocks
 - [Stepper](stepper.md) - Step-by-step content
 - [Tabs](tabs.md) - Tabbed content organization

docs/syntax/math.md

@@ -0,0 +1,141 @@
+# Math
+
+The `math` directive renders mathematical expressions using LaTeX syntax. Mathematical expressions are rendered client-side using KaTeX for fast, accurate display.
+
+## Basic usage
+
+:::::{tab-set}
+
+::::{tab-item} Preview
+
+:::{math}
+S(doc) = exp(\lambda \cdot max(0, |fieldvalue_{doc} - origin| - offset))
+:::
+
+::::
+
+::::{tab-item} Markdown
+
+```markdown
+:::{math}
+S(doc) = exp(\lambda \cdot max(0, |fieldvalue_{doc} - origin| - offset))
+:::
+```
+
+::::
+
+:::::
+
+## Display math
+
+For block-level mathematical expressions, use display math syntax:
+
+:::::{tab-set}
+
+::::{tab-item} Preview
+
+:::{math}
+\[
+\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
+\]
+:::
+
+::::
+
+::::{tab-item} Markdown
+
+```markdown
+:::{math}
+\[
+\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
+\]
+:::
+```
+
+::::
+
+:::::
+
+The directive automatically detects display math based on:
+- LaTeX display delimiters: `\[` and `\]`
+- TeX display delimiters: `$$` and `$$`
+- LaTeX environments: `\begin{...}` and `\end{...}`
+- Multi-line expressions
+- Complex expressions containing `\frac`, `\sum`, `\int`, `\lim`, etc.
+
+## Adding labels
+
+Label mathematical expressions for cross-referencing:
+
+:::::{tab-set}
+
+::::{tab-item} Preview
+
+:::{math}
+:label: einstein-equation
+E = mc^2
+:::
+
+::::
+
+::::{tab-item} Markdown
+
+```markdown
+:::{math}
+:label: einstein-equation
+E = mc^2
+:::
+```
+
+::::
+
+:::::
+
+This creates an element with `id="einstein-equation"` that can be referenced elsewhere in the document.
+
+## Complex expressions
+
+The math directive supports complex LaTeX expressions:
+
+:::::{tab-set}
+
+::::{tab-item} Preview
+
+:::{math}
+\begin{align}
+\frac{\partial f}{\partial x} &= \lim_{h \to 0} \frac{f(x+h) - f(x)}{h} \\
+\nabla \cdot \vec{E} &= \frac{\rho}{\epsilon_0}
+\end{align}
+:::
+
+::::
+
+::::{tab-item} Markdown
+
+```markdown
+:::{math}
+\begin{align}
+\frac{\partial f}{\partial x} &= \lim_{h \to 0} \frac{f(x+h) - f(x)}{h} \\
+\nabla \cdot \vec{E} &= \frac{\rho}{\epsilon_0}
+\end{align}
+:::
+```
+
+::::
+
+:::::
+
+## Supported LaTeX features
+
+The math directive supports most common LaTeX mathematical notation:
+
+- **Fractions**: `\frac{numerator}{denominator}`
+- **Superscripts and subscripts**: `x^2`, `x_i`
+- **Integrals**: `\int`, `\iint`, `\iiint`
+- **Sums and products**: `\sum`, `\prod`
+- **Limits**: `\lim`, `\limsup`, `\liminf`
+- **Greek letters**: `\alpha`, `\beta`, `\gamma`, etc.
+- **Matrices**: `\begin{matrix}`, `\begin{pmatrix}`, etc.
+- **Aligned equations**: `\begin{align}`, `\begin{eqnarray}`
+- **Roots**: `\sqrt{x}`, `\sqrt[n]{x}`
+- **Operators**: `\sin`, `\cos`, `\log`, `\exp`, etc.

src/Elastic.Documentation.Site/Assets/main.ts

@@ -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) {

src/Elastic.Documentation.Site/Assets/styles.css

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