Numerals Obsidian Plugin

Numerals gives you the power of an advanced calculator inside a math code block, complete with currencies, units, variables, and math functions! Now you can perform calculations inline with your notes, and see both the input and the evaluated result. Numerals works with Live Preview as well as Reader view, and offers TeX-style rendering or Syntax Highlighting as well as auto-completion suggestions. Comments or explanations can be added with #, and important results can be indicated with => after the calculation.

To get started, simply install and enable the plugin. Add a math code block with your desired calculations:

```math
20 mi / 4 hr to m/s

## Features

- Units

- `1ft + 12in` → `2ft`
- `20 mi / 4 hr to m/s` → `2.235 m / s`
- `100 km/hr in mi/hr` → `62.137 mi / hr`
- `9.81 m/s^2 * 100 kg * 40 m` → `39.24 kJ`
- Currency

- `$1,000 * 2` → `2,000 USD`
- `£10 + £0.75` → `10.75 GBP`
- `$100/hr * 3days` → `7,200 USD`
- Set custom currencies, for example `₿`
- Math functions

- `sqrt`, `sin`, `cos`, `abs`, `log`, etc \(see [mathjs](https://mathjs.org/docs/reference/functions.html) for full list\)
- Hex, Binary, Octal, and other bases

- `0xff + 0b100` → `259`
- `hex(0xff + 0b100)` → `"0x103"`
- Natural Constants

- `e`, `i`, `pi`, `speedOfLight`, `gravitationConstant`, `vacuumImpedance`, `avogadro`
- And many more \(see [mathjs: Constants](https://mathjs.org/docs/reference/constants.html) and [mathjs: Units](https://mathjs.org/docs/datatypes/units.html) for more\)
- Auto-complete suggestions

- By default will offer auto-complete suggestions for any variables defined in a math codeblock being edited
- Optional setting to include all available functions, constants, and physical constants
- Totals of previous lines using `@total` or `@sum` special operator

- When Numerals encounters `@total` or `@sum` it inserts the sum of all previous lines up until the last blank line or comment
- Previous result

- Use previous line result in current calculation with `@prev`
- Greek Letters

- Variables can be named using greek letters, e\.g\. `μ = 3 m/s`
- Greek letters can be auto-completed by typing `:`, e\.g\. `:mu` in a math block will offer `μ` as an auto-complete suggestion
- Note-Global Variables

- Any variable name or function definition preceeded by an `$` symbol will be made available to all math blocks on a page
- Fractions:

- `fraction(1/3) + fraction(1/4)` → `7/12`
- Comments and Headings:

- `#` at the end of a line will be ignored, but rendered in faint text as a comment
- A line starting with `#` will be ignored by the math engine, but will be bolded when rendered
- Result Annotation:

- `=>` at the end of a line \(but before a comment\) will tell *Numerals* that a result should be highlighted\. Any line in that code block *without* a `=>` annotation will be rendered faintly \(or hidden depending on settings\)\.
- Result Insertion:

- Using the `@[...]` syntax \(for example: `@[profit]`\), Numerals will insert the results of a calculation into the raw text of your note, following `::`
- Uses dataview notation, which allows writing back to dataview values\. For example, `@[profit]` will be modified to say `@[profit::10 USD]`
- Access Frontmatter Properties

- Numerals math blocks will have access to any property name specified in the `numerals:` property\. Setting `numerals` to `all`, will make all properties in a note available to *Numerals*
- Multiple properties can be specified as a list, e\.g\. `numerals: [apples, pears]` will makes both the `apples` and `pears` property available to Numerals
- Any property in the YAML frontmatter beginning with `$` automatically becomes a note-global variable \(or function\) accessible in every math block on the page
- Functions can be defined in YAML by name along with their arguments, e\.g\. `$f(x): x+2`

*Numerals* utilizes the [mathjs](https://mathjs.org/) library for all calculations\. *Numerals* implements a preprocessor to allow more human-friendly syntax, such as currency symbols and thousands separators\. For all available functions and capabilities \(which includes matrices, vectors, symbolic algebra and calculus, etc\), see the [mathjs documentation](https://mathjs.org/docs/index.html)

## Styling Options

*Numerals* has been tested with the default theme and most other top themes\. It uses default values such that it should play nice with any other theme\. There are also several configurable settings to modify how *Numerals* renders math blocks

### Render Style

*Numerals* supports rendering inputs/ouputs as either:

1. Plain Text
1. TeX
1. Syntax Highlighting

One of these options can either be chosen as a default from *Numerals* settings, or then can be applied on a per-block basis by using `math-plain`, `math-tex`, or `math-highlight` rather than a `math` code block\.

### Layout

#### 2-panes

- Answer is shown to the right of the input with a background color and a separator\.
- Distinctive style that separates input from evaluated answers

#### Answer to the Right

- Answer to the right: answer is shown in the same line as the input, but right-aligned
- More subtle than 2-panes that works well with just a few calculations

#### Answer Below

- Answer is shown below the input, on the next line\.
- Less compact vertically, but more compact horizontally

### Alternating Row Colors

Choose between a consistent code block background color \(left\), or alternating rows to help track from input to result \(right\)\.

### Auto-completion Suggestions

By default, *Numerals* will provide auto-completion suggestions for variables that have been defined in a particular `math` codeblock\. Turning on *Include Functions and Constants in Suggestions* will also provide suggestions for all functions, math constants, and physical constants supported in *Numerals*\.

### Format of Numbers in Rendered Results

*Numerals* allows the user to specify the format of rendered results\.

- **System Formatted** \(Default\): Use your local system settings for number formatting \(including thousands and decimal separator\)
- **Fixed**: No thousands separator and full precision\. Period as decimal separator \(e\.g\. `100000.1`\)
- **Exponential**: Always use exponential notation\. \(e\.g\. `1.000001e5`\)
- **Engineering**: Exponential notation with exponent a multiple of 3\. \(e\.g\. `100.0001e3`\)
- **Formatted**: Forces a specific type of formatted notation\.

- Style 1: `100,000.1`
- Style 2: `100.000,1`
- Style 3: `100 000,1`
- Style 4: `1,00,000.1`

## Installation

*Numerals* can be found in the Obsidian community plugin list\.

### Using BRAT

To try the latest features of *Numerals* before they are released, and provide helpful feedback and testing, try *Numerals* by using the [Obsidian BRAT plugin](https://github.com/TfTHacker/obsidian42-brat)\. **All new *Numerals* features will be pushed to beta testers first\.**

1. Ensure BRAT is installed
1. Trigger the command `Obsidian42 - BRAT: Add a beta plugin for testing`
1. Enter this repository, `gtg922r/obsidian-numerals`
1. Activate *Numerals* plugin in community plugin list

## Features in progress and roadmap

- Support for mapping currency symbols to different currencies \([\#17](https://github.com/gtg922r/obsidian-numerals/issues/17)\) both `$` and `¥` can be mapped to different currencies in settings
- Style Settings support for all colors and other style options \([\#13](https://github.com/gtg922r/obsidian-numerals/issues/13)\)

- Partial support added in 1\.0\.5
- Result annotation, similar to Calca feature \([\#4](https://github.com/gtg922r/obsidian-numerals/issues/4)\)

- Support added in 1\.0\.5
- Autocompletion of functions and variable inside math code block \([\#15](https://github.com/gtg922r/obsidian-numerals/issues/15)\)

- Support added in 1\.0\.8
- Inline calculation for inline code blocks \([\#5](https://github.com/gtg922r/obsidian-numerals/issues/5)\)

Feel free to suggest additional features by creating an [issue](https://github.com/gtg922r/obsidian-numerals/issues)\!

## Development

*Numerals* uses a three-stage development workflow: **Version → Build → Release**

### 1\. Version Management

Update the version number in `package.json`:

npm run version:patch # 1.5.1 → 1.5.2 npm run version:minor # 1.5.1 → 1.6.0 npm run version:major # 1.5.1 → 2.0.0 npm run version # defaults to patch

These commands only update the version in `package.json` and do not sync to manifests or create releases\.

### 2\. Build

Compile the TypeScript and bundle the plugin:

npm run build # Build for production npm run dev # Build for development with watch mode

The `build` command compiles TypeScript and creates the `main.js` file that Obsidian loads\.

### 3\. Release

Create tagged releases that trigger automated GitHub Actions:

#### Beta Releases

npm run release:beta

- Creates a timestamped beta version \(e\.g\., `1.5.1-beta.2024-01-15T10-30-00`\)
- Updates `manifest-beta.json` with the beta version
- Builds the project
- Creates a git tag and pushes it to trigger GitHub Actions
- Automatically creates a beta release on GitHub

#### Production Releases

npm run release:production # Full command npm run release # Shortcut for production

- Uses the current version from `package.json`
- Updates `manifest.json` and `versions.json`
- Builds the project
- Creates a git tag and pushes it to trigger GitHub Actions
- Automatically creates a production release on GitHub

### Complete Development Workflow

1. **Make changes** to the codebase
1. **Test locally** with `npm run dev`
1. **Increment version**: `npm run version:patch` \(or minor/major\)
1. **Test with beta release**: `npm run release:beta`
1. **Create production release**: `npm run release`

The release scripts handle all manifest syncing, building, tagging, and triggering GitHub Actions for automated release publishing\.

## Related

There are a number of other plugins that address math and calculation use cases in Obsidian\.

- If you are primarily interested in evaluating math expressions and inserting the result into your notes, look into [meld-cp/obsidian-calc](https://github.com/meld-cp/obsidian-calc)
- If you are looking for a full-featured Computer Algebra System including plots and with similar code block rendering, consider [Canna71/obsidian-mathpad: Computer Algebra System \(CAS\) for Obsidian\.md](https://github.com/Canna71/obsidian-mathpad)

There are also a number of \"calculator as notes\" apps that acted as the inspiration for *Numerals*\. If you are looking for a purpose-built app outside of Obsidian, consider:

- [Numi\. Beautiful calculator app for Mac\.](https://numi.app/)
- [Numbr](https://numbr.dev/)
- [Soulver 3 - Notepad Calculator App for Mac](https://soulver.app/)