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.

Values in charts

A chart can draw from your values. In a mermaid block, write a $name where a number goes:

$rent = 2400
$food = 1800

```mermaid
pie title Monthly costs
  "Rent" : $rent
  "Food" : $food
```

The chart shows the current values and redraws when they change. It works wherever the diagram expects a number: pie slices, bars and lines (bar [$q1, $q2]), axis ranges (y-axis "PLN" 0 --> $max), and task durations in a gantt chart (Review :a1, 2026-01-01, $days d).

One name, one number. A chart takes a bare $name, not an expression. Put the calculation on its own line ($net = $price * $qty) and reference $net in the chart.
Numbers only. A percent or a true/false value cannot be drawn. The chart tells you which name is the problem (“$vat is not a number”, “Unknown variable $rent”).
Labels stay text. A $name inside quotes ("Cost in $usd") or in a %% comment is left exactly as written.
Rename follows. Renaming a value in its definition line updates the charts that use it.
One color for one value. A value a chart draws takes the color of its slice, in every formula where it appears and in every chart, even under a different label. Values no chart draws keep their own color.
Ordinary code blocks are untouched. Only diagrams read your values; a $variable in a bash or any other code block is always literal.

A few things to know. The file keeps $rent, not the number, so another editor that renders mermaid (Obsidian, VS Code) will report a syntax error for that chart; Return is what resolves the value. And a chart placed inside a quote or a list item does not read values: keep charts that use them at the top level of the document. PDF and HTML export draw the chart with the values filled in.

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.

Export

PDF and HTML export show every formula the way the editor does: the line as you wrote it, with its result beside it. Results are formatted with your system’s number format, and a formula that cannot be computed exports with the same short code the chip shows, such as #div/0. In a PDF the formulas of one block form a small two-column table, formula on the left and result on the right; in HTML they keep the chip layout.

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. The one exception is reading: a mermaid diagram can reference your values (see Values in charts), but it can never define one.
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.