Math & LaTeX

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
{  "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

mdx
The algorithm runs in $O(n \log n)$ time and $O(n)$ space.$$T(n) = 2T\left(\frac{n}{2}\right) + O(n)$$

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]$$

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 for math rendering. KaTeX supports a large subset of LaTeX math syntax, covering the vast majority of documentation needs.

Supported Features

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. If a function is not listed there, it will render as an error in the output.

Performance Considerations

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.