Numerals turns Obsidian code blocks into a calculator with units and currency

A code block that evaluates itself

The pitch in the README is that Numerals turns Obsidian notes into living calculations, using math blocks or inline expressions to calculate with units, currencies, variables, functions, frontmatter, Dataview metadata and values from other notes. The mechanism is a math code block whose lines are evaluated by mathjs, with the results rendered back into the block. The quick start is a block with named variables and a trailing arrow:

# Lemonade stand
cups = 120
price = $1.50
revenue = cups * price
lemons = $18
sugar = $7
profit = revenue - lemons - sugar =>

@@C1@@The arrow is what marks the line whose result is the answer, and the README says to use it to highlight important results, with lines without a highlighted result able to be dimmed or hidden depending on your settings. That is a small design decision with a large effect on how a note reads. A working-out with five lines does not have to show five results, so the note keeps the reasoning and shows the answer. The inline form is a piece of ordinary inline code with a trigger prefix, so the same engine is reachable inside a sentence rather than only inside a block, and it works in Live Preview and in Reading mode, supporting the same math engine, number formatting, units, currency symbols, variables, frontmatter and Dataview values as the blocks do. The examples in the README use the default dollar sign to US dollar mapping and US English number formatting, and the separators follow your selected number format.

Two trigger prefixes, and one of them shows the working

The inline syntax table is small and the difference between the two prefixes is a presentation choice rather than a feature difference. A plain inline calculation renders only the answer, and the README gives the example of three feet times four feet producing twelve square feet. The equation prefix renders the expression and the answer together, so the same expression shows as three feet times four feet equals twelve square feet, and the README calls that the show-your-work form. The second form is for when the calculation itself is important, as in the perimeter of a room worked out from two dimensions. Both trigger prefixes and the equation separator are configurable in the Numerals settings, so a note can be written to whichever convention you prefer, and that matters when a vault is shared between people. Inline TeX triggers are the exception. The README is explicit that they belong to the unpublished 1.11.0 recovery preview, while the stable release supports TeX rendering inside math blocks, so a vault that relies on inline TeX expressions has to wait for the preview to land in the plugin browser. Math blocks are the safer place to start, and the at-a-glance table in the README shows both the inline and the block forms side by side with their outputs.

Units and currency are units, and there is no exchange rate

Numerals uses mathjs for the calculation and adds Obsidian-friendly preprocessing for currency symbols and readable number input, which is what lets you write a thousand with a comma rather than an escaped thousand. The capability list covers unit arithmetic such as one foot plus twelve inches giving two feet, conversions such as 72 degrees Fahrenheit to degrees Celsius, currency such as a thousand dollars times two, rates such as a hundred dollars an hour for three days, mathjs functions including square roots, sine and logarithms, base arithmetic such as hexadecimal plus binary, and fractions such as one third plus one quarter giving seven twelfths. The one limitation is stated plainly in the README: Numerals treats currencies as units, it does not fetch exchange rates and it does not automatically convert between currencies. A note that mixes dollars and euros will add them as if they were the same thing, which is a real trap in a document about international pricing, and the fix is a rate expressed by hand inside the note. Currency symbols can be customised in settings, so a note can use a different symbol for a different currency, but the symbol is a label and not a conversion.

Note-wide variables, previous results and totals

Three mechanisms let a note carry state across its own calculations. A variable or function prefixed with a dollar sign becomes note-wide, and the README's example defines a rate and a discount function in one block and then uses both in inline expressions elsewhere in the same note, with note-wide variables working across math blocks and inline expressions alike. The at-prev marker refers to the previous result, so a chain of percentage increases reads as a base, a first multiplication and then the previous value multiplied again, in a block or inline. The at-total and at-sum markers add up the previous results up to the last blank line or heading or comment, which turns a list of figures into a running subtotal. The state is scoped to the note, which is the right scope for a note-taking tool and also the limit, since nothing here crosses into other notes except through the explicit cross-note reference syntax. The auto-complete suggestions that appear while typing draw on the same pool: variables from the current block, note-wide dollar variables, frontmatter and Dataview metadata, cross-note properties once a wiki link has been opened, mathjs functions and constants, and Greek letters typed with a colon prefix.

Frontmatter and cross-note references are opt-in

Reading numbers out of a note's properties is opt-in by default, and the mechanism is a property in the frontmatter. You select the note properties Numerals should read with the numerals property, and the README's example exposes price and quantity, with a dollars-prefixed frontmatter value automatically becoming a note-wide variable:

---
numerals: [price, quantity]
price: 29.99
quantity: 150
---

`#=: price * quantity`

@@C2@@Using numerals: all exposes every frontmatter property instead. Dataview inline fields and metadata work too when the Dataview plugin is installed, using the same selection, or by enabling the always process all frontmatter setting. Cross-note references are the same idea pointed at another file, with a wiki link followed by a property path, and the referenced note exposes its own properties the same way. Nested properties use dot notation, with the README giving two examples:

[[config]].rates.hourly
[[project/invoice]].lineItems.total

@@C3@@When the referenced metadata changes, Numerals rerenders the dependent inline values, so a price held in one note propagates into a calculation in another. That is the feature that turns a collection of notes into a small calculation graph, and it is also the feature that couples your notes together, because renaming a frontmatter key in one file breaks the reference in another with no compile step to catch it.

Result insertion writes back into the raw note

The most unusual feature is that a calculation can edit the note it lives in. The at-sign label syntax writes a result back into the raw note as Dataview-style inline metadata, so a line that reads a labelled assignment gains the computed value inside the label, and with US English number formatting Numerals updates the value while keeping the assignment and the expression intact. The README shows the before and after forms, where a labelled assignment becomes the same assignment with a value added after a double colon. The effect is that a note can hold a live figure without the figure being typed, which is what makes the plugin useful for a running total or a computed rate that appears in prose. The cost is that the note's source is modified, so the raw file and the rendered view diverge, and a user has to accept that rather than treat it as a free feature. The README also notes that rendered math blocks remain editable in Live Preview, since clicking or tapping a rendered Numerals line focuses the underlying text for editing, which is what keeps a rewritten value from becoming an obstacle.

Two release channels, and the interesting one is not published

The release table at the top of the README is the part to read before installing anything. There is a stable 1.10.2 available through Obsidian's Community Plugins browser, and the guide describes that published release. Alongside it is a recovery preview 1.11.0, under development for Obsidian 1.13 and later, which the README says is not yet published, including through BRAT, the community plugin installer used for beta builds. The reason for the preview is implicit in the naming: it is a recovery path for a host application change, so if you are on Obsidian 1.13 and the stable release does not work, the preview is the option and it is not something you can get from the plugin browser. The recent GitHub releases show the same split, with 1.10.2, then 1.10.1 and 1.10.0 both marked as betas, and the 1.10.0 release note naming cross-note references, click-to-edit and release hardening. The package metadata shows the plugin is called obsidian-numerals, built with esbuild and TypeScript, tested with jest and jsdom, and depending on mathjs at 15.2.0 with fast-deep-equal. The project is MIT licensed, and the last push to the repository was on 2026-09-14.

Editorial conclusion

Numerals suits an Obsidian user whose notes hold numbers, whether that is a rate card in frontmatter, a budget worked out in a code block, or a spec where quantities multiply out. It does not suit a team that needs the figures in a database or a spreadsheet rather than in notes, and the split between a stable release and an unpublished preview is worth checking before you rely on it. Before adopting, install the 1.10.2 release from Obsidian's Community Plugins browser rather than the preview, decide whether to opt frontmatter in per note, and note that the last push to the repository was on 2026-09-14 with the newest published release 1.10.2 from 2026-05-19.

Frequently asked questions

Official sources

1. gtg922r/obsidian-numerals on GitHub
2. Issues
3. License: MIT
4. README
5. Releases