Formulas

Formulas turn a document into a living calculation. Define a value once, reference it in later formulas, and Return shows the results next to each line - interest, contractual penalties, settlement scenarios - without a spreadsheet and without leaving the text.

Everything is computed locally, instantly, and deterministically. Results are shown next to your text but are never written into the file: the document stays plain markdown, fully readable in any other editor.

Defining a value

Start a line with $ and give the value a name - a named formula creates a variable you can reference anywhere in the document:

$principal = 120 000
$rate = 11,5%
$months = 8

The result appears at the right edge of each line, and consecutive formula lines group into one calculation block - a blank line starts a new block. Values are visible in the whole document (order doesn’t matter - you can reference a value before the line that defines it), and each document has its own private set: nothing leaks between files.

Names can use letters (including accented characters), digits and _, and must start with a letter or _: $kwota, $rate_2026, $całość.

Each name is defined once per document. A second $name = ... line for the same name is flagged with #duplicate - the first definition stays in effect.

Quick calculations

A $ line without name = is a quick formula - it evaluates without storing anything:

$ 120 000 * 11,5% / 12
$ $principal * $rate
$principal

The last form - just a reference on its own line - shows the current value.

Comments

Annotate a formula with // - everything after it is a note, not part of the calculation:

$rata = $cena / 12 // monthly, per §4 of the contract
$ // financing costs
$odsetki = $rata * 5%

A $ // line with only a comment works as a label inside a calculation block. Notes are dimmed so the formula and its result stay in the foreground, and a $name mentioned inside a note is just text - it is not a reference.

Numbers

Both decimal separators work: 0,5 and 0.5 are the same number. Thousands can be grouped with spaces: 1 000 000. Results are displayed using your system’s number format.

One rule to remember: a comma directly followed by a digit is always a decimal separator - 1,500 means one and a half. When listing function arguments, separate them with a comma plus a space, or with a semicolon: min(1,5; 2).

Percent

A percent sign attached to a number makes it a percentage, with natural semantics:

$net = 10 000
$ $net + 23%     -> 12 300   (adding a percent scales the value)
$ $net - 10%     -> 9 000
$ $net * 5%      -> 500      (multiplying takes the fraction)
$vat = 23%

With a space, % is the remainder operator instead: 10 % 3 is 1.

Operators and functions

Arithmetic: + - * / ^ (power), % (remainder, with spaces). Comparisons: < > <= >= = !=, combined with &&, ||, !.

The function set is deliberately small:

Function	Meaning
`if(condition, then, else)`	pick one of two values
`match(x, v1, r1, v2, r2, ..., default)`	multi-way branch on a value
`min(...)`, `max(...)`	smallest / largest argument
`round(x)` or `round(x, digits)`	rounding
`clamp(x, low, high)`	constrain a value to a range

$cap = 15 000
$penalty = clamp($principal * $rate, 0, $cap)
$tier = match($months, 12, 10%, 24, 15%, 5%)
$ if($penalty >= $cap, 1, 0)

if() and match() evaluate only the branch they pick, so a guard like if($months = 0, 0, $total / $months) is safe - the division never runs when the guard says no.

Formulas are calculations, not a programming language: there are no loops, no multi-line blocks, no text values.

Tip: put spaces around operators ($a * 3, not $a*3). It reads better, and asterisks glued to names can be styled as markdown emphasis in the editor.

Formulas in tables

A table cell whose entire content is a formula referencing your values shows its result next to the cell content:

Item	Amount
$principal	$principal * $rate

Cells that merely mention a $name inside prose (“payable: $principal net”) stay plain text - only a cell that IS a formula participates. Results in cells follow the same rules as lines: they update live and are never written into the file.

When something can’t be computed

Errors show as a short code in the chip, in place of a value:

Code	Meaning
`#unresolved`	the referenced value is not defined in this document
`#cycle`	definitions reference each other in a circle (`$a = $b`, `$b = $a`)
`#ref`	a referenced variable has an error of its own
`#div/0`	division (or remainder) by zero
`#duplicate`	this name was already defined above
`#syntax`	the expression could not be parsed
`#error`	the expression is malformed in another way (wrong number of arguments, an unknown function)

Fix the underlying line and every dependent result recomputes immediately.

Working with results

Copy a value - click the result chip.
Inspect a reference - hover any $name to see its value and where it’s defined.
Jump to the definition - cmd+click (ctrl+click) a reference.
See where a value is used - place the cursor on a definition line; its references in other formulas light up.
Autocomplete - type $ and pick from the values defined in the document.
Insert a reference by pointing - while your cursor is in a formula, alt+click any $name in another formula to insert it at the cursor - like clicking a cell while writing a spreadsheet formula. Hold alt and the name you’re pointing at underlines when the click will work.
Rename safely - edit the name right in its definition line and every formula that uses it follows along, including table cells. Prose is never touched, and one undo takes the whole rename back.

What variables are not

Only lines that start with $ participate. A $ inside prose (“the fee is $rate of the amount”) is plain text - nothing in your prose is ever interpreted.
Code blocks are literal. A $name = ... line inside a fenced code block is not evaluated.
Results are never saved into the file. The document on disk contains only what you typed. Opened in another editor, it reads perfectly - just without the live results.

Formulas vs placeholders

They look related but serve different jobs:

Placeholders ([UPPERCASE]) are fill-in fields - inputs you (or the AI) replace with text when generating a document from a template.
Formulas ($name) are calculations - numbers the editor computes and keeps up to date while you write.

A template can use both: placeholders for the parties and dates, formulas for the amounts that follow from them.