Numerals

Numerals turns Obsidian notes into living calculations. Use math blocks or inline expressions to calculate with units, currencies, variables, functions, frontmatter, Dataview metadata, and values from other notes.

At a Glance

Quick Start

Add a math code block anywhere in a note:

```math
revenue = $2,400
expenses = $850
profit = revenue - expenses =>
```

Or calculate directly in a sentence:

The project total is `#: $150/hr * 8hr`.

Use equation mode when the calculation itself is important:

The room perimeter is `#=: 2 * (12ft + 10ft)`.

Core Features

Inline Calculations

Inline Numerals expressions are ordinary inline code with a trigger prefix:

Inline calculations work in Live Preview and Reading mode. They support the same math engine, number formatting, units, currency symbols, variables, frontmatter, and Dataview values as math blocks.

Math Blocks

Numerals math blocks are ideal for longer calculations:

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

Use => to highlight important results. Lines without a highlighted result can be dimmed or hidden depending on your settings.

Units, Currency, and Functions

Numerals uses mathjs for calculations and adds Obsidian-friendly preprocessing for currency symbols and readable number input.

Currency symbols can be customized in settings.

Note-Wide Variables

Prefix a variable or function with $ to make it available across the whole note:

```math
$rate = $150/hr
$discount(x) = x * 0.9
```

Estimate: `#: $rate * 40hr`
Discounted: `#: $discount($rate * 40hr)`

Note-wide variables work across math blocks and inline expressions.

Previous Results

Use @prev to refer to the previous result:

```math
base = 100
base * 1.2
@prev * 1.08
```

Inline expressions can use @prev too:

First year: `#: 100 * 1.2`
Second year: `#: @prev * 1.08`

Totals

Use @total or @sum to add previous results up to the last blank line or heading/comment:

```math
$12
$18
$25
@total =>
```

Frontmatter and Dataview Metadata

Numerals can read selected note properties from frontmatter:

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

`#=: price * quantity`

Use numerals: all to expose all frontmatter properties to Numerals. $-prefixed frontmatter values are automatically available as note-wide variables.

Dataview inline fields and metadata can also be used in calculations when Dataview is installed.

Cross-Note References

Reference frontmatter and Dataview metadata from other notes with [[note]].property:

```math
hours = 12 hr
subtotal = [[Client Settings]].rates.hourly * hours
tax = subtotal * [[Client Settings]].taxRate
total = subtotal + tax =>
```

Nested properties use dot notation:

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

Cross-note references work in math blocks and inline expressions. When referenced metadata changes, Numerals rerenders dependent inline values.

Result Insertion

Use @[label] to write a result back into the raw note as Dataview-style inline metadata:

```math
@[profit] = $2,400 - $850
```

Numerals updates the source text to:

@[profit::1,550 USD]

Auto-Complete

Auto-complete suggestions work in math blocks and inline Numerals expressions. Suggestions can include:

• Variables from the current block
• Note-wide $ variables
• Frontmatter and Dataview metadata
• Cross-note properties after [[note]].
• mathjs functions and constants
• Greek letters by typing :, such as :mu -> μ

Click to Edit in Live Preview

Rendered math blocks remain easy to edit. Click or tap a rendered Numerals line in Live Preview to focus the matching source line.

Display Options

Numerals is designed to fit naturally with Obsidian themes and supports multiple render styles.

Render Style

Choose a default render style in settings, or set it per block:

Layouts

Choose how results appear next to calculations:

• Two panes: input and result in separate columns.
• Answer to the right: compact inline result display.
• Answer below: result appears on the next line.

Number Formatting

Configure how rendered numbers are displayed:

• System formatted: follows your local system separators.
• Fixed: full precision with no thousands separator.
• Exponential: scientific notation.
• Engineering: exponent is a multiple of 3.
• Formatted: choose a specific thousands/decimal style.

Installation

Install Numerals from Obsidian's Community Plugins browser.

Pre-Release Testing

To test upcoming releases before they reach the stable Obsidian directory:

1. Install the BRAT plugin.
2. Run Obsidian42 - BRAT: Add a beta plugin for testing.
3. Enter gtg922r/obsidian-numerals.
4. Enable Numerals in Community Plugins.

Development

Numerals is an Obsidian community plugin written in TypeScript and bundled with esbuild.

Local Commands

npm install
npm run dev
npm test
npm run lint
npm run build

Versioning

Update the version number in package.json:

npm run version:patch
npm run version:minor
npm run version:major

These commands only update package.json. Stable release metadata is updated by the production release script.

Mathjs Symbol Suggestions

Auto-complete suggestions for mathjs functions and constants are kept as a static list in src/mathjsUtilities.ts.

When upgrading mathjs, run:

npm run symbols:check

If the check finds intentional changes, run:

npm run symbols:update

Review the generated diff and adjust explicit exclusions in scripts/mathjs-symbols.ts for documented symbols that should not appear in suggestions.

Releases

Create a pre-release for BRAT users:

npm run release:beta

Promote a tested version to the stable Obsidian release channel:

npm run release

Production releases update manifest.json and versions.json, build the project, commit stable release metadata, and promote the matching GitHub release. GitHub Actions generates release assets from the tag, including a tag-matched manifest.json, and creates GitHub Artifact Attestations for uploaded files.

Related

Other Obsidian calculation plugins may fit different workflows:

• obsidian-calc for calculator-style expression evaluation and result insertion.
• obsidian-mathpad for a fuller computer algebra system inside Obsidian.

Numerals is also inspired by calculator-as-notes apps such as Numi, Numbr, and Soulver.