README file from
GithubLaTeX Vault
An Obsidian plugin that renders LaTeX code blocks in your vault using a local TeX installation (MiKTeX / TeX Live), producing SVG images: TikZ diagrams, pgfplots, matrices, algorithms, code listings, and math with any installed package, including the ones TikZJax cannot load.
Features
- Renders
latex-vault blocks (plus legacytikz,tikzcd,pgfplots) to SVG using your local TeX (MiKTeX / TeX Live), in both Reading mode and Live Preview (while respecting Source Mode). - Supports any LaTeX package (
pgfplots,circuitikz,tikz-cd,forest,nicematrix,algorithmicx,listings, ...), unlike TikZJax. - Automatic
pdflatex + dvisvgm/latex + dvisvgmfallback, automatic second pass fornicematrixand cross-references, bounded concurrency, and SVG-only disk caching. - Dark mode adaptation: choose between automatic color inversion (preserving hues), a light paper card, or unmodified rendering.
- In Live Preview, collapsed blocks act as atomic units behind a "Show LaTeX code" toggle; expanded edits are debounced so typing does not trigger intermediate compilations.
- Smart wrapping: bare TikZ commands,
scope, andpgfplotsaxes are wrapped in atikzpicture, while self-contained environments (forest,circuitikz,quantikz,karnaugh-map,bytefield) and non-picture content (matrices, algorithms, code listings, math) are typeset as-is. - Command Palette actions (Clear LaTeX rendering cache, Toggle LaTeX live preview) and optional shell-escape (off by default) for packages that run external tools.
Requirements
- Obsidian desktop 1.5.0+ (Windows, macOS, Linux).
- A local TeX installation with
latex/pdflatexanddvisvgmon yourPATH(or configured in the plugin settings):
| Platform | Recommended TeX | Notes |
|---|---|---|
| Windows | MiKTeX or TeX Live | MiKTeX vs TeX Live flags are detected automatically; native .exe paths are checked if not on PATH |
| macOS | MacTeX / TeX Live | standard paths like /Library/TeX/texbin are checked automatically |
| Linux | TeX Live (texlive-full) |
binaries usually in /usr/bin |
For the build you also need Node.js.
Installation
From Obsidian Community Plugins (Recommended)
- Open Settings → Community plugins → Browse in Obsidian.
- Search for LaTeX Vault, click Install, and then Enable.
From Source
- Clone the repo and build:
git clone https://github.com/GodJeam/latex-vault.git
cd latex-vault
npm install
npm run build
- Copy the generated files into your vault:
<vault>/.obsidian/plugins/latex-vault/
├── main.js
├── manifest.json
└── styles.css
- In Obsidian: Settings → Community plugins → enable LaTeX Vault.
Usage
Wrap LaTeX code in a ```latex-vault fenced block:
```latex-vault
\begin{tikzpicture}
\draw (0,0) circle (1);
\end{tikzpicture}
```
Blocks are not limited to diagrams: matrices, pseudocode, code listings and formulas work too:
```latex-vault
$\begin{pNiceMatrix} 1 & 2 \\ 3 & 4 \end{pNiceMatrix}$
```
```latex-vault
\begin{algorithmic}
\For{$i = 1$ to $n$}
\State $s \gets s + a_i$
\EndFor
\end{algorithmic}
```
Preamble and packages
Leading lines with preamble commands (\usepackage, \usetikzlibrary, \newcommand, \lstset, ...) are moved to the preamble. A block containing \documentclass is compiled verbatim; one containing \begin{document} only gets the missing class and tikz.
tikz, amsmath and amssymb are always loaded. These packages are loaded automatically when their environments/commands are detected (unless you load them yourself):
| Detected | Package |
|---|---|
tikzcd |
tikz-cd |
axis, groupplot, polaraxis, ternaryaxis, smithchart, \addplot |
pgfplots (compat=1.18) + matching library |
forest / circuitikz / quantikz |
forest / circuitikz / quantikz |
karnaugh-map / bytefield |
karnaugh-map / bytefield |
pNiceMatrix, NiceArray, ... / blockarray |
nicematrix / blkarray |
algorithmic |
algpseudocode |
lstlisting / minted / tcolorbox |
listings / minted / tcolorbox |
\dv, \pdv, \bra, \ket |
physics |
\coloneqq, \mathclap, ... |
mathtools |
\cancel / \SI, \qty, \num, ... |
cancel / siunitx |
Floats (algorithm, figure, table) are forced to the [H] placement so they render inside the standalone image; \begin{algorithm} loads algorithm automatically unless you load algorithm2e.
Any other installed package can be loaded with \usepackage in the block or in the Extra preamble setting. A full TeX installation (e.g. texlive-scheme-full) avoids missing-package errors.
minted: recent TeX Live versions run it in restricted mode. If yours does not, enable shell-escape in the settings (only for trusted vaults, since it lets code blocks execute commands).
The latex-vault tag is dedicated to the plugin, so Obsidian's latex syntax highlighting keeps working for code you only want to show. The tikz, tikzcd and ```pgfplots tags still work for existing notes.
In the plugin settings you can configure the dark mode adaptation, rendering engine, binary paths, an extra preamble, shell-escape, and the interface language (English by default, Italian optional). Use the Test button to run an uncached check of your TeX setup, or trigger Clear LaTeX rendering cache and Toggle LaTeX live preview from the Command Palette.
Privacy & Data Handling
LaTeX Vault runs entirely locally inside Obsidian without telemetry, analytics, or network requests; all rendering is performed by your local TeX binaries (pdflatex/latex and dvisvgm).
- Settings: Stored in
<vault>/.obsidian/plugins/latex-vault/data.jsonand validated on load. - Render cache: Compiled SVGs are stored in a user-private temporary directory (
$TMPDIR/latex-vault-render-<uid>,0700directory,0600files) and expire automatically after 14 days (capped at 256 MB). Intermediate.tex,.aux,.log,.pdf, and.dvibuild files are removed immediately after each compilation. - SVG sanitization: Produced SVGs are scoped with unique per-diagram ID prefixes and sanitized via Obsidian's
sanitizeHTMLToDombefore being inserted into the DOM. - Shell escape & Windows launchers: Enable shell-escape is off by default; enable it only for trusted vaults. On Windows,
.cmd/.batlaunchers are rejected to avoidcmd.exeshell execution (use native.exebinaries).
Project Structure
src/
├── main.ts # Plugin entry point, commands, Reading Mode post-processor & settings validation
├── renderer.ts # TeX source generation, bounded local compilation & SVG caching
├── livePreview.ts # CodeMirror 6 Live Preview extension & fence discovery
├── settings.ts # Plugin settings tab & uncached TeX configuration test
├── ui.ts # Shared DOM helpers for SVG figures, loading status & errors
├── languages.ts # Supported fenced block tags & CommonMark fence parser
└── i18n.ts # Type-safe English and Italian translations
build/
├── esbuild.config.mjs # Production/dev bundler
├── run-tests.mjs # Offline Node test runner
└── tsconfig.json # TypeScript configuration
test/
├── mock-tex.mjs # Offline mock TeX/dvisvgm simulator
└── suite.test.ts # Unit and integration tests (npm test)
Contributing
Development happens on the dev branch. Read CONTRIBUTING.md before opening a Pull Request.
License
GPL-3.0, see LICENSE.