Why the editor works the way it does. To use a feature, see the User guide; for a task, the How-to guides.

How the editor behaves, and why

The pages of this guide each describe one part of the editor. A handful of rules run through all of them, and knowing them makes most of the editor’s choices predictable.

Your files are the truth

The task board is todo.md; a whiteboard is its .canvas file; your settings are a commented text file. There is no second copy kept in a database for the editor to fall out of step with: the board reads the file, a card moved is a line moved in it, and an edit made by hand — or by Obsidian, or by git — is what the board shows next. The cost is that a feature is only as rich as its file can say: a whiteboard card has one colour because JSON Canvas has one. The gain is that every one of your notes, tasks and boards opens in another program, today and in ten years.

Nothing leaves your machine

The editor makes no network request of its own: previews do not fetch pictures from the internet, a link card shows its address rather than a preview of the page, exports carry their pictures inside. What it remembers about you — open files, recent folders, local history, the colours you used — lives in your own data folder, never in the project, so nothing it keeps turns up in git status or in somebody’s clone. The few things that do reach out are yours to start: git fetching and pushing, and a page exported to be drawn by its reader’s browser.

Nothing fails in silence

A font that is not installed, a stylesheet a rule cannot find, a spell checker that is missing, a file that could not be written: each is said in the status bar, and the editor carries on with what it has. A setting that falls back quietly is a setting somebody spends an afternoon doubting, so falling back is always allowed and hiding it never is. The same rule is why a broken settings file opens the editor on the defaults instead of stopping it.

Speed is measured, not hoped

Every operation that has to feel instant has a written budget — 16 ms for anything inside a frame, 4 ms for a keystroke’s work — measured on a 2017 laptop on every change, and a missed budget fails the build. That is why some features are bounded in ways that look arbitrary: a whiteboard does not draw the words of cards too small to read, a search stops at a thousand files, the heavy preview is a separate program that costs nothing until opened. Each bound is where a measurement said the experience would otherwise break.

Settings explain themselves

Every option is written in your settings file with what it does, in your language, and the defaults live in a file too. A setting is a line you can read, not a checkbox hidden three dialogs deep; a project can override any of them in its own .kaivalya/settings.toml, writing only what differs.

Two languages, both first

The interface, the settings file and this documentation exist in English and in French, each written in its own language rather than translated word for word, and a feature is not finished until both say it.

Previews and exports: which draws what

A markdown document can be drawn in four places, by two different renderers. They differ for reasons, and once the reasons are clear, which one to look at stops being a question.

The two renderers

The live preview — beside the text (Ctrl+Shift+B) or instead of it (Ctrl+Shift+V) — is drawn inside the editor, by the same toolkit that draws its menus and its text. That is what lets it repaint after every keystroke at no cost, and follow the cursor heading by heading. The price is that it is not a browser: it draws in the editor’s own theme, ignores your stylesheet, and shows the constructs it does not know — a $formula$, an alert’s [!TIP], a mermaid block — as the text you typed.

The heavy preview (Ctrl+Shift+P) and the export are drawn by an HTML engine — Blitz, with Stylo, Firefox’s own style system, for the CSS — that the editor runs as a separate program. That is what makes your CSS mean what it says, and lets the editor draw maths and diagrams as pictures. The price is memory: about 117 MB while the window is open, nothing when it is not. Which is why it is a window you open, not a pane that is always there.

The heavy preview is the export, before it is written. They are one page, built once: what you see in that window is the file Export as HTML writes, apart from one line that lets the window find your pictures on your disk — a line the export leaves out, because it would tell the reader where the file lives.

Side by side

Live preview Heavy preview Export as HTML Export, drawn by the browser
Where beside or instead of the text its own window a .html file a .html file
Your stylesheet no — the editor’s theme yes, exactly yes, exactly yes, exactly
Follows typing every keystroke every pause — —
Maths $…$ the TeX you typed drawn, as SVG drawn, as SVG drawn by MathJax when opened
Mermaid diagrams the source drawn, as SVG drawn, as SVG drawn by mermaid.js when opened
Alerts > [!TIP] a quotation with its icon, foldable with its icon, foldable with its icon, foldable
Embeds ![[note]] a link the note, put in the note, put in the note, put in
Code colours yes yes yes yes
Needs the network no no no yes, to draw
Memory nothing extra about 117 MB while open — —

The two exports differ only in who draws the maths and the diagrams. The ordinary one draws them here, so the page needs nothing — no network, no script — and looks exactly like the heavy preview. The second leaves them as TeX and mermaid source and writes two script addresses into the page, so the reader’s browser fetches MathJax and mermaid.js and draws them: better maths, the whole of mermaid, at the cost of a page that reaches out to somebody’s server when it is opened.

Which to use

  • Writing: the live preview. It keeps up, and it is right about structure — headings, lists, tables, links, emphasis — which is what you check while writing.
  • Checking how it will look to somebody else: the heavy preview. Your stylesheet, your images at their size, the formulae and diagrams as they will be drawn.
  • Sending it: Export as HTML, pictures inside the page, and you have one file that works anywhere and offline. Print it from a browser for a PDF.
  • Publishing maths that must be perfect, or a diagram the editor cannot draw: the export drawn by the browser.

Why not one renderer

One renderer would have to be fast enough to redraw on every keystroke and a whole browser engine. Those pull in opposite directions: a browser engine is fast at drawing a page and slow at being started, and it holds memory whether or not you are looking. So the editor keeps the always-there preview cheap and honest about its limits, and puts the faithful one a keystroke away, costing nothing until you ask for it.

And the network

The editor itself never fetches anything — not for a preview, not for an export. A picture at an https:// address is left as that address, shown as its alt text in the heavy preview, and loads for whoever opens an exported page with a connection. The one way a page reaches out is the export drawn by the browser, and that is the reader’s browser fetching the two scripts whose addresses are in your settings (export_mathjax_url, export_mermaid_url) — never this editor. More in The heavy preview and Exporting as HTML.