Repository navigation
How it works
What happens between a tikz code block and the picture in your note. The reasoning behind each decision is written down in the repository, in CONTRIBUTING.md and internal/DECISIONS.md.
flowchart LR
A["tikz block"] --> C{"cached?"}
C -- yes --> Z["SVG in<br/>the note"]
C -- no --> E["TeX in a<br/>Web Worker"]
P["saved<br/>preamble"] -.-> E
E -- DVI --> F["dvi2html,<br/>sanitize"]
F -- SVG --> G["cache"]
G --> Z
E -. "TeX error" .-> X["error card"]
Obsidian hands the plugin the text of each tikz block. The plugin takes out the %!tikz option lines, reads any preamble files the block uses, and hashes all of it together with the revision of what the engine draws, the SVG pipeline's revision and the options that change the output. That hash is the cache key. If the key is in the memory cache, and no preamble file is configured, the stored SVG goes into the note before the code block processor returns, in the same frame as the text around it. A hit in IndexedDB, after a restart, takes a moment longer. Neither runs TeX. Theme, width and alignment are not part of the key, so changing them never recompiles anything. Since 0.2.1 the key holds a revision of what the engine draws rather than the exact build of the engine, so a release that only makes the engine faster leaves the cache as it was.
A diagram that is not cached starts the engine at once, if it is not running, and goes to the engine as soon as it scrolls into view. Only a diagram in a note you are typing in waits for you to pause first, so that typing compiles it once per pause rather than at every keystroke. TeX runs in a Web Worker, so Obsidian stays responsive while it works. On a phone one diagram compiles at a time; on a computer two can, each in an engine of its own, while several new diagrams wait. Diagrams that come into view together go to the engine from the top of the note down. If a diagram runs past its time limit (10 seconds on a desktop, 20 on a phone, unless you change it), its engine is stopped and started again, and only that diagram fails. A diagram on which TeX gives up, with a macro that never stops expanding or a hundred errors, does not wait for the limit: it fails at once, with TeX's own message.
When TeX has finished, its DVI output is turned into SVG with dvi2html, still in the worker. A character the engine has no font for, Chinese, Greek, Cyrillic and the like, reaches the SVG as a box one em wide that TeX set aside for it, and the worker writes the character over it as text in the system's sans-serif font. Back in the plugin, the SVG is sanitized (only what the engine itself emits is let through), its ids are made unique so two diagrams on a page cannot clash, and its black and white are marked as ink and paper so that CSS can follow your theme. The stored SVG never depends on the theme. Then it goes into the cache, in memory and in IndexedDB.
Nothing in this goes over the network. The engine, the TeX files and the fonts are all inside main.js and styles.css, and CI checks the source for anything that could make a request.
The engine is TeX itself: e-TeX with a LaTeX format, compiled from its original Pascal source to WebAssembly by web2js, the way TikZJax does it. The people who made that possible are named in the README's credits. Four small change files of my own go on top: one adds \ifincsname, which LaTeX's ~ and its current UTF-8 support need; one makes LaTeX's check for a file answer no when the file is not there; one closes TeX's files properly when a fatal error ends the run, so that its message and any page it finished are kept; and, since 0.2.1, one adds the point at the end of \begin{document} where a diagram's preamble is saved. Since 0.2.0 the engine has no asyncify, and its build is pinned to WebAssembly 1.0, which a test checks. Since 0.2.1 three files of web2js's code generator are replaced with my own, so that TeX's local variables are WebAssembly locals, which a JavaScript engine can keep in the processor's registers, and binaryen 132 optimises the result; together with calls into the plugin that no longer make new arrays, TeX takes about a third less time. The TeX packages are TeX Live 2023's, as Ubuntu 24.04 ships them.
Loading LaTeX and TikZ from scratch for every diagram would be slow, so the engine starts from a memory image instead: TeX's whole memory, saved once LaTeX, the standalone class, TikZ and xcolor are loaded. It is 156 MiB, mostly zeros, and only the parts that hold anything, about 22 MiB, go into main.js, compressed. Since 0.2.1 the plugin hands them to the engine when it starts it, and the engine unpacks them with the system's own decompression where there is one (on an iPhone from iOS 16.4); on my desktop a start takes about 54 ms in Chromium, the browser engine of Obsidian's desktop app, where 0.2.0's took about 160. An engine keeps one block of memory for TeX, and before each diagram puts back only what the diagram before it changed, about 27 MiB, in a couple of milliseconds. An idle engine is stopped after five minutes on a desktop, and after 15 seconds, or as soon as you switch away from Obsidian, on a phone, so that it gives its memory back.
Since 0.2.1, when TeX reaches the end of a diagram's \begin{document}, with its packages, libraries and preamble loaded, the engine keeps the part of TeX's memory that loading them changed. A later diagram whose text is the same up to that point starts from there, and TeX compiles only its body: on my desktop, circuitikz drawn a second time took 64 ms of TeX in Chromium where it took 214 from the start. The saved preambles are also kept in the device's own storage, in IndexedDB beside the diagram cache and never in the vault, so that the first diagram after the engine stops, or after Obsidian restarts, starts from one too. A diagram drawn this way is the same, byte for byte, as one drawn from the start, and CI checks that for every test diagram and for 33 cases written to break it. Settings → Saved preambles turns them off. The README's questions say what a saved preamble holds and how much room they take.
The engine is built in a Docker container from pinned upstream commits, and the build is reproducible: the same inputs give the same bytes, and CI rebuilds it to check. The result, about 8.5 MiB with the WebAssembly, the memory image, 247 TeX files and 152 fonts, is committed to the repository, so building the plugin itself needs neither Docker nor the fifteen minutes the engine takes:
npm ci
npm run build| Path | What is there |
|---|---|
src/block/ |
One diagram's life: a small state machine, the placeholder, mounting, error cards |
src/cache/ |
The cache key; the cache in memory, in IndexedDB, and the original TikZJax plugin's cache, read but never changed; the stored preambles |
src/queue/ |
The render queue |
src/engine/ |
Starting, feeding, timing and restarting the engines, and which engine a diagram goes to |
engine-src/ |
The worker: TeX's host, its in-memory file system, the memory reset, saved preambles, the text for characters without a font, dvi2html |
src/svg/ |
The SVG pipeline: sanitize, ids, optimisation, colours |
src/source/, src/preamble/
|
Option lines, the pre-flight check, preamble files |
engine-build/ |
Building the engine itself |
CONTRIBUTING.md lists the checks CI runs and the rules a change has to keep: no network requests, the community store's rules, Obsidian 1.7.2 as the floor, nothing iOS Safari cannot parse, and reproducible output. If you want to work on something, say so in Discussions or on the issue first, so we do not both do it.
Something wrong or missing on these pages? Say so in Discussions.