> ## Documentation Index
> Fetch the complete documentation index at: https://docs.holydocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Math & LaTeX

Render mathematical equations and formulas in your documentation using LaTeX syntax.

## Overview

HolyDocs supports LaTeX math rendering via KaTeX, a fast math typesetting library that produces publication-quality output directly in the browser. Once enabled, you can write inline equations and display-mode formulas anywhere in your MDX content.

## Enabling LaTeX

LaTeX rendering is disabled by default. Enable it in your `docs.json`:

```json docs.json
{
  "styling": {
    "latex": true
  }
}
```

When `latex` is set to `true`, the KaTeX stylesheet and font files are included in your site's build output. This adds approximately 300KB to the initial page load (fonts are loaded on demand). Only enable it if your documentation uses math notation.

## Inline Math

Wrap LaTeX expressions in single dollar signs to render them inline with surrounding text:

```mdx
The quadratic formula is $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$ where $a \neq 0$.
```

Inline math flows naturally within paragraphs. Use it for variable references, short expressions, and formulas that are part of a sentence.

### More Inline Examples

```mdx
The time complexity is $O(n \log n)$ in the average case.

Euler's identity states that $e^{i\pi} + 1 = 0$.

The probability is given by $P(A|B) = \frac{P(B|A) \cdot P(A)}{P(B)}$.
```

## Display Math

Wrap LaTeX in double dollar signs on their own lines for centered, display-mode equations:

```mdx
The Gaussian integral:

$$
\int_{-\infty}^{\infty} e^{-x^2} \, dx = \sqrt{\pi}
$$
```

Display math is rendered larger than inline math, centered on the page, and separated from surrounding content with vertical spacing. Use it for important formulas, derivations, and equations that deserve visual emphasis.

The opening `$$` and closing `$$` must each be on their own line with no other content. Placing them inline (e.g., `$$x = 1$$`) will not render correctly in display mode.

## Common LaTeX Examples

### Fractions and Roots

```mdx
$$
\frac{n!}{k!(n-k)!} = \binom{n}{k}
$$

$$
x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

$$
\sqrt[3]{27} = 3
$$
```

### Superscripts and Subscripts

```mdx
$$
a_1, a_2, \ldots, a_n
$$

$$
x^{2n+1} + y^{2n+1} = z^{2n+1}
$$

$$
\sum_{i=1}^{n} x_i = x_1 + x_2 + \cdots + x_n
$$
```

### Integrals

```mdx
$$
\int_0^1 x^2 \, dx = \frac{1}{3}
$$

$$
\iint_D f(x, y) \, dA
$$

$$
\oint_C \mathbf{F} \cdot d\mathbf{r}
$$
```

### Matrices

```mdx
$$
A = \begin{pmatrix}
a_{11} & a_{12} & a_{13} \\
a_{21} & a_{22} & a_{23} \\
a_{31} & a_{32} & a_{33}
\end{pmatrix}
$$

$$
\det(A) = \begin{vmatrix}
a & b \\
c & d
\end{vmatrix} = ad - bc
$$
```

### Greek Letters

```mdx
Lowercase: $\alpha, \beta, \gamma, \delta, \epsilon, \zeta, \eta, \theta, \iota, \kappa, \lambda, \mu$

Uppercase: $\Gamma, \Delta, \Theta, \Lambda, \Xi, \Pi, \Sigma, \Phi, \Psi, \Omega$

Common uses: $\pi \approx 3.14159$, $\theta \in [0, 2\pi)$, $\lambda = 0.05$
```

### Summations and Products

```mdx
$$
\sum_{k=0}^{n} \binom{n}{k} = 2^n
$$

$$
\prod_{i=1}^{n} x_i = x_1 \cdot x_2 \cdots x_n
$$

$$
\lim_{n \to \infty} \left(1 + \frac{1}{n}\right)^n = e
$$
```

### Set Notation

```mdx
$$
A \cup B = \{x : x \in A \text{ or } x \in B\}
$$

$$
A \cap B \subseteq A \cup B
$$

$$
\forall x \in \mathbb{R}, \exists n \in \mathbb{N} : n > x
$$
```

### Aligned Equations

```mdx
$$
\begin{aligned}
f(x) &= (x + 1)^2 \\
     &= x^2 + 2x + 1 \\
     &= (x + 1)(x + 1)
\end{aligned}
$$
```

### Cases (Piecewise Functions)

```mdx
$$
f(x) = \begin{cases}
x^2 & \text{if } x \geq 0 \\
-x^2 & \text{if } x < 0
\end{cases}
$$
```

## Practical Documentation Examples

### Algorithm Complexity

**Sorting**

```mdx
    The algorithm runs in $O(n \log n)$ time and $O(n)$ space.

    $$
    T(n) = 2T\left(\frac{n}{2}\right) + O(n)
    $$
    ```
  **Machine Learning**

```mdx
    The cross-entropy loss function:

    $$
    L = -\frac{1}{N} \sum_{i=1}^{N} \left[ y_i \log(\hat{y}_i) + (1 - y_i) \log(1 - \hat{y}_i) \right]
    $$
    ```
  **Statistics**

```mdx
    The standard deviation of a sample:

    $$
    s = \sqrt{\frac{1}{N-1} \sum_{i=1}^{N} (x_i - \bar{x})^2}
    $$
    ```

### Pricing Formula

When documenting pricing calculations, billing logic, or financial APIs:

```mdx
The monthly cost is calculated as:

$$
\text{cost} = \text{base\_price} + \left(\max(0, \text{usage} - \text{included}) \times \text{rate}\right)
$$

where $\text{included}$ is the number of free units on your plan.
```

## KaTeX Support Details

HolyDocs uses [KaTeX](https://katex.org/) for math rendering. KaTeX supports a large subset of LaTeX math syntax, covering the vast majority of documentation needs.

### Supported Features

| Category | Examples |
|---|---|
| Arithmetic | `+`, `-`, `\times`, `\div`, `\pm`, `\cdot` |
| Relations | `=`, `\neq`, `<`, `>`, `\leq`, `\geq`, `\approx` |
| Greek letters | `\alpha` through `\Omega` |
| Functions | `\sin`, `\cos`, `\log`, `\exp`, `\lim`, `\max`, `\min` |
| Operators | `\sum`, `\prod`, `\int`, `\iint`, `\oint` |
| Accents | `\hat{x}`, `\bar{x}`, `\vec{x}`, `\dot{x}`, `\tilde{x}` |
| Delimiters | `\left(`, `\right)`, `\langle`, `\rangle`, `\lfloor`, `\rfloor` |
| Fonts | `\mathbb{R}`, `\mathcal{L}`, `\mathbf{v}`, `\mathrm{const}` |
| Environments | `aligned`, `cases`, `pmatrix`, `bmatrix`, `vmatrix` |
| Spacing | `\,`, `\;`, `\quad`, `\qquad`, `\text{ }` |

### Unsupported Features

A small number of advanced LaTeX features are not available in KaTeX:

- `\usepackage` and custom macro definitions via `\newcommand` (in preamble style)
- TikZ diagrams and pgfplots
- `\begin{figure}` and other float environments
- `\label` and `\ref` cross-referencing

For the full list of supported functions, see the [KaTeX function support table](https://katex.org/docs/supported.html). If a function is not listed there, it will render as an error in the output.

## Performance Considerations

**Only enable when needed**

The KaTeX CSS and font files add approximately 300KB to your documentation bundle. If your docs do not contain mathematical notation, leave `"latex": false` (the default) to keep your site lean.
  **Fonts load on demand**

KaTeX fonts are loaded only when the page contains math content. Pages without LaTeX expressions do not download the font files, even when the feature is globally enabled.
  **Rendering is fast**

KaTeX renders math at build time where possible and falls back to client-side rendering for dynamic content. Server-rendered math avoids layout shift and produces instant visual results.
  **Prefer display mode for complex expressions**

Inline math with deeply nested fractions, tall delimiters, or multi-line constructs can disrupt line height and paragraph rhythm. Move complex expressions to display mode (`$$...$$`) for better readability.

## Accessibility

KaTeX generates MathML alongside its visual output. Screen readers that support MathML can read equations aloud, providing access to math content for visually impaired users.

For critical equations, consider adding a text description below the formula:

```mdx
$$
E = mc^2
$$

*Energy equals mass times the speed of light squared.*
```

This ensures the meaning is accessible even when MathML support is unavailable.

When writing inline math within descriptive text, the surrounding prose should provide enough context for a reader to understand the formula without seeing it rendered. For example, "the time complexity is $O(n \log n)$" is clear even as plain text.

## Escaping Dollar Signs

When LaTeX is enabled, dollar signs have special meaning. To display a literal `$` character in your content (e.g., for currency), escape it with a backslash:

```mdx
The API costs \$0.01 per request after the free tier.
```

Alternatively, use inline code to display dollar amounts:

```mdx
The API costs `$0.01` per request after the free tier.
```