✅ Introduction

The Scimax VS Code extension provides comprehensive LaTeX preview functionality for org-mode documents, enabling inline rendering of mathematical equations and formulas. This feature brings publication-quality mathematics directly into your editing workflow without requiring manual compilation or external viewers.

✅ What is LaTeX Preview?

LaTeX preview is a system that automatically compiles and renders LaTeX mathematical expressions as images when you hover over them in your org-mode documents. This provides instant visual feedback for complex equations, matrices, and mathematical notation.

✅ Key Features

Hover Preview: Rendered equations appear in tooltips when hovering over LaTeX code
Multiple Syntax Styles: Support for both dollar-sign and backslash delimiters
Dark Mode Aware: Automatically adjusts rendering for light and dark themes
Smart Caching: Previously rendered equations are cached for instant display
Document Settings: Use custom LaTeX packages and preambles
Equation Numbering: Automatic numbering for equation environments
Live PDF Preview: Full document preview with bidirectional sync

✅ Math Syntax

✅ Inline Math

Inline math appears within text paragraphs and uses the following delimiters:

✅ Dollar Sign Delimiter: $...$

The most common inline math syntax. Text between single dollar signs is rendered as mathematics.

The quadratic formula is $x ` \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$ for equation $ax^2 + bx + c ' 0$.

✅ Backslash-Parenthesis Delimiter: `$...$`

Alternative inline math syntax, preferred in some LaTeX style guides.

Einstein's mass-energy equivalence is $E = mc^2$, where $c$ is the speed of light.

✅ Currency Detection

The preview system intelligently avoids treating dollar amounts as math. Currency patterns like $100 or $5.99 are ignored.

✅ Display Math

Display math appears on its own line, centered and larger than inline math.

✅ Double Dollar Signs: `$$...$$`

Creates unnumbered display equations.

\[\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}\]

∫₋∞^∞ e^(-x²) dx = √π

Backslash Brackets: `\[...\]`

Alternative display math syntax, equivalent to $$...$$.

\[
\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}
\]

∑(n1 to ∞) 1/n² π²/6

Math Environments

LaTeX environments provide advanced layout and automatic numbering.

Equation Environment

Single numbered equations with automatic numbering.

\begin{equation}
E = mc^2
\end{equation}

E = mc² (1)

Equation* Environment (Unnumbered)

Same as `equation' but without numbering.

\begin{equation*}
F = ma
\end{equation*}

Align Environment

Multi-line equations with alignment points (`&').

\begin{align}
x + y &= 5 \\
2x - y &= 1
\end{align}

x + y = 5 (2) 2x - y = 1 (3)

Each line receives its own equation number.

Align* Environment (Unnumbered)

Multi-line alignment without equation numbers.

\begin{align*}
\nabla \times \mathbf{E} &= -\frac{\partial \mathbf{B}}{\partial t} \\
\nabla \times \mathbf{H} &= \mathbf{J} + \frac{\partial \mathbf{D}}{\partial t}
\end{align*}

Other Numbered Environments

All these environments support automatic equation numbering:

`gather' - Multiple centered equations
`multline' - Single equation split across lines
`eqnarray' - Legacy alignment (prefer `align')
`alignat' - Alignment with explicit spacing
`flalign' - Full-width alignment

Add an asterisk (*) after the environment name for the unnumbered version: gather*, multline*, etc.

Matrix Environments

Specialized environments for matrices and arrays:

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

`matrix' - Plain matrix (no delimiters)
`pmatrix' - Matrix with parentheses ( )
bmatrix - Matrix with brackets [ ]
`vmatrix' - Matrix with single bars | |
`Vmatrix' - Matrix with double bars || ||
`smallmatrix' - Compact inline matrix

Previewing Math Fragments

Hover Preview

To preview any LaTeX math expression:

Position your cursor over the math expression
Wait briefly or hover with your mouse
A tooltip appears showing the rendered equation

The preview displays:

The rendered equation as an image (SVG or PNG)
Equation number (if applicable)
The original LaTeX source code

Preview Caching

Rendered equations are cached in your VS Code global storage directory. The cache:

Speeds up repeated hover previews
Persists between VS Code sessions
Automatically cleans up entries older than 7 days
Stores separate versions for light and dark modes

Clearing the Cache

To clear all cached equation renders:

Open Command Palette (C-S-P / s-S-P)
Run: Scimax: Clear LaTeX Cache

To view cache statistics:

Open Command Palette
Run: Scimax: Show LaTeX Cache Statistics

This displays:

Number of cached equations
Total cache size on disk

LaTeX Fragment Settings

Document-Level Configuration

Add LaTeX configuration at the top of your org file using #+LATEX_HEADER: keywords.

Custom Packages

Load additional LaTeX packages for special symbols or functionality:

#+LATEX_HEADER: \usepackage{physics}
#+LATEX_HEADER: \usepackage{siunitx}
#+LATEX_HEADER: \usepackage{chemformula}

Now you can use commands from these packages:

physics: \grad, \div, \curl, \laplacian
siunitx: \SI{10}{\meter\per\second}
chemformula: \ch{H2O}, \ch{CO2}

Custom Commands

Define your own LaTeX macros:

#+LATEX_HEADER: \newcommand{\RR}{\mathbb{R}}
#+LATEX_HEADER: \newcommand{\dd}[1]{\,\mathrm{d}#1}
#+LATEX_HEADER: \DeclareMathOperator{\Tr}{Tr}

Use in equations:

$$\int_{\RR} f(x) \dd{x} = \Tr(A)$$

Custom Preamble

For extensive customization, add multiple headers:

#+LATEX_HEADER: \usepackage{amsmath,amssymb,amsfonts}
#+LATEX_HEADER: \usepackage{mathtools}
#+LATEX_HEADER: \usepackage{bm}
#+LATEX_HEADER: \usepackage{physics}
#+LATEX_HEADER: \DeclareMathOperator{\sgn}{sgn}
#+LATEX_HEADER: \newcommand{\ve}[1]{\bm{#1}}

VS Code Settings

Configure global LaTeX preview behavior in your settings.

Enable/Disable Preview

Completely enable or disable hover previews.

{
  "scimax.latexPreview.enabled": true
}

Cache Control

Enable or disable caching of rendered equations. Disabling may slow down previews but saves disk space.

{
  "scimax.latexPreview.cacheEnabled": true
}

Dark Mode Awareness

When enabled, equations render with white text on dark backgrounds when using dark themes, and black text for light themes.

{
  "scimax.latexPreview.darkModeAware": true
}

Common LaTeX Math Commands

Greek Letters

Lowercase

Command	Symbol	Command	Symbol
\alpha	α	\nu	ν
\beta	β	\xi	ξ
\gamma	γ	\pi	π
\delta	δ	\rho	ρ
\epsilon	ε	\sigma	σ
\zeta	ζ	\tau	τ
\eta	η	\upsilon	υ
\theta	θ	\phi	φ
\iota	ι	\chi	χ
\kappa	κ	\psi	ψ
\lambda	λ	\omega	ω
\mu	μ

Uppercase

Command	Symbol	Command	Symbol
\Gamma	Γ	\Xi	Ξ
\Delta	Δ	\Pi	Π
\Theta	Θ	\Sigma	Σ
\Lambda	Λ	\Phi	Φ
\Upsilon	Υ	\Psi	Ψ
\Omega	Ω

Math Operators

Command	Output	Description
\frac{a}{b}	a/b	Fraction
\sqrt{x}	√x	Square root
\sqrt[n]{x}	ⁿ√x	nth root
x²	x²	Superscript (power)
x_i	xᵢ	Subscript
\int	∫	Integral
\sum	∑	Summation
\prod	∏	Product
\lim	lim	Limit
\partial	∂	Partial derivative
\nabla	∇	Nabla (gradient)
\infty	∞	Infinity

Relations and Operators

Command	Symbol	Command	Symbol
\leq	≤	\geq	≥
\neq	≠	\approx	≈
\equiv	≡	\sim	∼
\propto	∝	\in	∈
\notin	∉	\subset	⊂
\supset	⊃	\cup	∪
\cap	∩	\wedge	∧
\vee	∨	\neg	¬
\times	×	\div	÷
\pm	±	\mp	∓
\cdot	·	\circ	∘

Arrows

Command	Symbol	Description
\rightarrow	→	Right arrow
\leftarrow	←	Left arrow
\Rightarrow	⇒	Implies
\Leftarrow	⇐	Implied by
\Leftrightarrow	⇔	If and only if
\uparrow	↑	Up arrow
\downarrow	↓	Down arrow
\to	→	Alternative for →
\mapsto	↦	Maps to

Special Symbols

Command	Symbol	Description
\mathbb{R}	ℝ	Real numbers
\mathbb{N}	ℕ	Natural numbers
\mathbb{Z}	ℤ	Integers
\mathbb{Q}	ℚ	Rational numbers
\mathbb{C}	ℂ	Complex numbers
\emptyset	∅	Empty set
\forall	∀	For all
\exists	∃	There exists
\ell	ℓ	Script lowercase L
\hbar	ℏ	Reduced Planck constant

Delimiters

Command	Output	Description
\left( \right)	( )	Auto-sized parentheses
\left[ \right]	[ ]	Auto-sized brackets
\left\{ \right\}	{ }	Auto-sized braces
\left	\right		\vert \vert	Auto-sized vertical bars
\langle \rangle	⟨ ⟩	Angle brackets
\lfloor \rfloor	⌊ ⌋	Floor function
\lceil \rceil	⌈ ⌉	Ceiling function

Accents and Decorations

Command	Example	Description
\hat{x}	x̂	Hat accent
\bar{x}	x̄	Bar (mean)
\tilde{x}	x̃	Tilde
\dot{x}	ẋ	Dot (derivative)
\ddot{x}	ẍ	Double dot
\vec{x}	x⃗	Vector arrow
\overline{AB}	AB̄	Overline
\underline{x}	x̲	Underline

Example Equations

Calculus

\[f'(x) = \lim_{h \to 0} \frac{f(x+h) - f(x)}{h}\]

\[\int_a^b f'(x) \,dx = f(b) - f(a)\]

\[\int u \,dv = uv - \int v \,du\]

Linear Algebra

\begin{pmatrix} a & b \\ c & d \end{pmatrix}

\begin{pmatrix} x \\ y \end{pmatrix}

\begin{pmatrix} ax + by \\ cx + dy \end{pmatrix}

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

\[A\mathbf{v} = \lambda\mathbf{v}\]

Physics

\[i\hbar \frac{\partial}{\partial t}\Psi(\mathbf{r},t) = \hat{H}\Psi(\mathbf{r},t)\]

\begin{align*} \nabla \cdot \mathbf{E} &= \frac{\rho}{\epsilon_0} \\ \nabla \cdot \mathbf{B} &= 0 \\ \nabla \times \mathbf{E} &= -\frac{\partial \mathbf{B}}{\partial t} \\ \nabla \times \mathbf{B} &= \mu_0\mathbf{J} + \mu_0\epsilon_0\frac{\partial \mathbf{E}}{\partial t} \end{align*}

Statistics

\[f(x) = \frac{1}{\sigma\sqrt{2\pi}} \exp\left(-\frac{(x-\mu)^2}{2\sigma^2}\right)\]

\[P(A|B) = \frac{P(B|A)P(A)}{P(B)}\]

Computer Science

\[T(n) = O(n\log n)\]

\[T(n) = 2T\left(\frac{n}{2}\right) + O(n)\]

Troubleshooting Rendering Issues

Common Problems and Solutions

Problem: "pdflatex not found" Error

Install a LaTeX distribution:

Linux: sudo apt-get install texlive-full
macOS: Install MacTeX from https://tug.orgmactex
Windows: Install MiKTeX from https:/miktex.org or TeX Live

After installation, restart VS Code.

Problem: Equations Not Rendering on Hover

LaTeX preview disabled
Syntax error in equation
Missing LaTeX package

Problem: Slow Hover Response

Enable caching (if disabled):
Clear corrupted cache:
Simplify complex equations:

Problem: Rendering Wrong in Dark Mode

Enable dark mode awareness:

{
  "scimax.latexPreview.darkModeAware": true
}

The equation will automatically render with appropriate colors for your theme.

Problem: Equation Numbers Wrong

The counter cache automatically invalidates when you edit the document. If numbers still appear incorrect, save the file and hover again.

Problem: dvisvgm Not Available

Install dvisvgm (usually included with full LaTeX distributions):

`sudo apt-get install texlive-binaries' (Linux)
Included with MacTeX and full TeX Live installations

Problem: Currency Detected as Math

This should not happen as the preview system detects dollar amounts starting with numbers. If it does occur:

Use \$100 to escape the dollar sign
Or use proper currency notation outside of math mode

Integration with Export

HTML Export

When exporting to HTML, LaTeX math is rendered using MathJax:

Inline math: $E mc²$= → Renders with MathJax in browser
Display math: $$...$$ → Centered equation in HTML
Environments: \begin{align}...\end{align} → Properly formatted

The export includes MathJax CDN automatically, so equations render perfectly in web browsers.

LaTeX/PDF Export

When exporting to LaTeX or PDF:

Math expressions are passed through unchanged
#+LATEX_HEADER: settings are included in preamble
Equation numbering preserved
All environments work natively

Export and Preview Consistency

What you see in hover preview should match the exported output, but note:

HTML export: Uses MathJax (may look slightly different from LaTeX preview)
PDF export: Uses your LaTeX compiler (exact match with preview)
Font differences: Preview uses default LaTeX fonts; exports may use custom fonts

Commands and Keybindings

Preview Commands

Command	Description	Keybinding
Scimax: Clear LaTeX Cache	Clear all cached equation renders	None (use Command Palette)
Scimax: Show LaTeX Cache Statistics	Display cache size and entry count	None

Live PDF Preview Commands

Command	Description	Keybinding
Scimax: Open LaTeX Live Preview	Open live PDF preview of document	C-c C-e l v
Scimax: Sync PDF to Cursor Position	Jump to cursor location in PDF	C-c C-e l s
Scimax: Rebuild PDF	Manually trigger PDF rebuild	None
Scimax: Show LaTeX Build Output	Show compiler output and errors	None

Markup Commands

Command	Description	Keybinding
Scimax: LaTeX Math (Markup)	Insert inline math $...$	None
Scimax: LaTeX Display Math (Markup)	Insert display math \[...\]	None

Using Commands

Via Command Palette:
Via Keybinding:

Custom Keybindings

To add custom keybindings for commands without defaults:

Open Keyboard Shortcuts (`C-k C-s')
Search for the command (e.g., "Clear LaTeX Cache")
Click the + icon to add a keybinding
Press your desired key combination

[
  {
    "key": "ctrl+alt+l",
    "command": "scimax.clearLatexCache",
    "when": "editorLangId == 'org'"
  }
]

Advanced Topics

Multi-line Equations

Use \\ to break equations across multiple lines within display math:

\[ f(x) = a_0 + a_1 x + a_2 x^2 + \cdots \\ = \sum_{n=0}^{\infty} a_n x^n \]

Aligned Equations at Specific Points

Use & in align environments to specify alignment points:

\begin{align*} x &= r\cos\theta \\ y &= r\sin\theta \end{align*}

The `&' symbols align vertically.

Cases and Piecewise Functions

Use the cases environment:

$$ f(x) = \begin{cases} x² & \text{if } x \geq 0

\end{cases} $$

Chemical Formulas

With the chemformula package:

The reaction is \ch{2 H2 + O2 -> 2 H2O}.

or with `mhchem'

The reaction is \ce{2 H2 + O2 -> 2 H2O}.

Physics Notation

With the physics package:

#+LATEX_HEADER: \usepackage{physics}

$$\dv{f}{x} = \lim_{h \to 0} \frac{f(x+h) - f(x)}{h}$$

$$\grad V = \left(\pdv{V}{x}, \pdv{V}{y}, \pdv{V}{z}\right)$$

SI Units

With the siunitx package:

#+LATEX_HEADER: \usepackage{siunitx}

The speed is \SI{3e8}{\meter\per\second}.

Best Practices

Document Organization

Place all #+LATEX_HEADER: lines at the top of your org file, before the first heading
Group related packages together with comments
Define custom commands early for use throughout the document

#+TITLE: Research Notes
#+AUTHOR: Your Name
#+DATE: 2026-01-13

# Standard math packages
#+LATEX_HEADER: \usepackage{amsmath,amssymb,amsfonts}
#+LATEX_HEADER: \usepackage{mathtools}

# Physics
#+LATEX_HEADER: \usepackage{physics}

# Custom commands
#+LATEX_HEADER: \newcommand{\RR}{\mathbb{R}}
#+LATEX_HEADER: \newcommand{\dd}[1]{\,\mathrm{d}#1}

* First Section

Writing Maintainable Math

Use meaningful variable names in comments:
Break complex equations into multiple lines:
Use consistent notation throughout your document
Define reusable commands for frequently used symbols

Performance Tips

Keep custom packages minimal - only load what you need
Use caching (keep scimax.latexPreview.cacheEnabled true)
Simplify very complex equations - LaTeX compilation can be slow for intricate formulas
Avoid excessive hover - let the cache build up naturally

Accessibility

When sharing documents:

Provide text descriptions for complex equations
Export to HTML for web accessibility (MathJax is screen-reader friendly)
Use semantic math rather than visual formatting

Quick Reference Card

Math Delimiters

Type	Syntax	Description
Inline	$...$	Dollar signs
Inline	`$...$`	Backslash parens
Display	`$$...$$`	Double dollar
Display	`\[...\]`	Backslash brackets
Environment	`\begin{...}\end{...}`	LaTeX environment

Common Environments

Environment	Numbered	Description
`equation`	Yes	Single equation
`equation*`	No	Single equation
`align`	Yes	Multi-line aligned
`align*`	No	Multi-line aligned
`gather`	Yes	Multi-line centered
`gather*`	No	Multi-line centered
`matrix`	N/A	Plain matrix
`pmatrix`	N/A	Matrix with ( )
`bmatrix`	N/A	Matrix with [ ]

Essential Commands

Category	Examples
Greek	`\alpha \beta \gamma \delta \lambda \sigma \omega`
Operators	`\frac \sqrt \sum \int \prod \lim`
Relations	`\leq \geq \neq \approx \equiv \in`
Arrows	`\to \rightarrow \Rightarrow \Leftrightarrow`
Sets	`\mathbb{R} \mathbb{N} \mathbb{Z} \emptyset`
Logic	`\forall \exists \wedge \vee \neg`
Calculus	`\partial \nabla \infty`
Delimiters	`\left( \right) \left[ \right] \left\{ \right\}`

Keybindings

Action	Keybinding
Open live preview	`C-c C-e l v`
Forward sync	`C-c C-e l s`
Export dispatcher	`C-c C-e`

Settings

Setting	Default	Description
`scimax.latexPreview.enabled`	`true`	Enable hover previews
`scimax.latexPreview.cacheEnabled`	`true`	Cache rendered equations
`scimax.latexPreview.darkModeAware`	`true`	Adapt to theme

Additional Resources

LaTeX Documentation

LaTeX Math Wiki: https://en.wikibooks.org/wiki/LaTeX/Mathematics
Comprehensive LaTeX Symbol List: http://tug.ctan.org/info/symbols/comprehensive/symbols-a4.pdf
Detexify (draw symbols): https://detexify.kirelabs.org/classify.html

Command	Description	Keybinding
Scimax: LaTeX Math (Markup)	Insert inline math \(...\)	None
Scimax: LaTeX Display Math (Markup)	Insert display math \[...\]	None