TikZ

TikZ (obsidian-tikz)

An Obsidian desktop plugin that renders ```tikz code blocks by shelling out to a locally installed TeX distribution (TeX Live, MacTeX, or MiKTeX) instead of a browser WASM engine.

Forked and rewritten from artisticat1/obsidian-tikzjax: settings scaffolding and the ```tikz code block tag are preserved for backward compatibility, while the rendering engine is completely replaced with native TeX execution.

Requirements

• Obsidian Desktop (Windows, macOS, Linux). Mobile is unsupported (no Node.js child processes).
• A TeX distribution with dvisvgm installed:
  • Windows: MiKTeX or TeX Live
  • macOS: MacTeX (or via Homebrew: brew install --cask mactex-no-gui)
  • Linux: TeX Live
    • Ubuntu/Debian: sudo apt install texlive-latex-extra texlive-luatex texlive-pictures dvisvgm
    • Fedora: sudo dnf install texlive-scheme-medium dvisvgm
    • Arch Linux: sudo pacman -S texlive-basic texlive-latexextra texlive-pictures dvisvgm
  • Linux Flatpak note: If running Obsidian via Flatpak (md.obsidian.Obsidian), the plugin automatically executes host TeX binaries via flatpak-spawn --host and uses ~/.cache/obsidian-tikz for scratch files without extra setup.

Installation

1. Download main.js, manifest.json, and styles.css from the latest GitHub Release.
2. Create a folder named <vault>/.obsidian/plugins/tikz/ in your vault.
3. Place the downloaded files into that folder.
4. Reload Obsidian and enable TikZ in Settings → Community plugins.

Usage

Place TikZ code inside a ```tikz block. Standard figures, bare snippets, or complete documents are all supported:

```tikz
\begin{document}
\begin{tikzpicture}
  \draw[thick, ->] (0,0) -- (1,1) node[right] {$x$};
\end{tikzpicture}
\end{document}
```

Bare TikZ snippets and packages loaded inline are also accepted:

```tikz
\usepackage{forest}
\begin{forest}
[VP [NP [Det][N]] [V]]
\end{forest}
```

Cache & Scratch Files

• Render cache: Compiled diagrams (<hash>.svg) are saved in <vault>/.obsidian/plugins/tikz/cache/ (hidden inside the plugin directory; zero vault pollution). Failed compiles are not cached; the error block shows the live compiler log. When the entry limit is reached, the least recently used diagrams are dropped first.
• Compile scratch files: Temporary TeX build files (.tex, .dvi, .log) live in your OS temp folder (os.tmpdir()/obsidian-tikz/, or ~/.cache/obsidian-tikz/ on Flatpak) and are cleaned up immediately upon completion.

Settings

[!NOTE] On macOS, GUI apps launched from Finder or the Dock do not inherit your shell's PATH. If binaries show as "not found", click Detect automatically or set the path manually (e.g. /Library/TeX/texbin).

Dark Mode Customization

• Adaptive (default): Automatically mirrors colour lightness while maintaining a 3:1 contrast floor, ensuring labels and shapes remain legible against dark themes.
• Light canvas: Keeps original colours untouched and shows the diagram on a light panel (ideal for complex shading, ball color, or colormaps).
• Off: Leaves colours unchanged.

To force a diagram to look identical in both light and dark themes, give it a background rectangle:

\usetikzlibrary{backgrounds}
\begin{tikzpicture}[
    show background rectangle,
    background rectangle/.style={fill=white, draw=none},
  ]
  \draw[thick, ->] (0,0) -- (1,1) node[right] {$x$};
\end{tikzpicture}

Security

• Shell escape is off by default: Vault content is untrusted; -shell-escape is never enabled unless explicitly turned on by the user.
• Direct argv execution: Subprocesses are spawned with an argv array (spawn/execFile), never interpolated shell strings.
• File reads are restricted: TeX runs with openin_any=p, so a note cannot \input or \includegraphics arbitrary files (e.g. ~/.ssh/config) into a diagram. It can be turned off in settings for trusted vaults.
• SVG sanitization (allowlist, fail-closed): The SVG is parsed and only the elements dvisvgm/PGF emit are kept; event handlers, external href/url() references, <style>, <a> and animation elements are removed. An SVG that cannot be parsed is rejected rather than displayed, and the result is inserted via DOMParser, never innerHTML.

Development

npm run dev     # watch build (outputs main.js)
npm run build   # typecheck + production bundle
npm run lint    # eslint
npm test        # vitest unit tests
npm run clean   # clean generated bundle files

See AGENTS.md for architectural constraints and contribution rules.

License

MIT. Scaffolding based on artisticat1/obsidian-tikzjax.

Showcase

Diagrams rendered side-by-side in Light mode (left) and Dark mode (right) with automatic adaptive contrast:

Mathematics & Geometry

Circuits & Scientific Plots

3D Coordinates & Diagrams

Automata & Theme Adaptation