Numerals
by RyanC
Score: 55/100
favorite
share
Description
Category: Coding & Technical Tools

The Numerals plugin is a powerful tool that enables users to perform mathematical calculations and insert the results into their Obsidian notes. With this plugin, you can write complex math expressions in Markdown code blocks and evaluate them instantly. The plugin also offers advanced features such as result annotation, autocompletion of functions and variables, and style settings for customization. Additionally, Numerals supports mapping currency symbols to different currencies and allows users to specify the format of rendered results. Overall, this plugin is an excellent choice for anyone who needs to perform complex calculations or visualize data in their Obsidian notes.

Stats
454
stars
37,387
downloads
12
forks
844
days
287
days
292
days
8
total PRs
1
open PRs
2
closed PRs
5
merged PRs
83
total issues
37
open issues
46
closed issues
39
commits
Latest Version
10 months ago
Changelog

🚀 Numerals 1.5 - Biggest Update Yet! 🚀

Introducing some of the most requested features including the ability to:

  • sum previous lines with @sum or @total
  • reference note frontmatter properties
  • use global variables between blocks
  • insert calculation results directly into your notes

Also new convenience features such as Greek letter auto-completion and custom currency support. Upgrade now and take your note-taking calculations to the next level!

Detailed Updates

⭐️ Sums and Totals of Previous Lines

  • New feature and syntax for summing a group of lines: @sum or @total (closes #18, #49, #36)
  • When Numerals encounters @total or @sum it inserts the sum of all previous lines up until the last blank line or comment
  • Can use in a calculation or unit conversion

2024-06-11 Sum and Totals Example

⭐️ Values in Note Frontmatter

Numerals can now reference note frontmatter or dataview inline values. Set the numerals property on a page to share specific properties with all math blocks on a page.

In order to access metadata, you need to tell Numerals to make the value available by:

  1. Set the numerals metadata value (either frontmatter or dataview inline property) to the name of the value you want to include, or a list of values
    • Frontmatter of numerals: other_metadata_name, or numerals: [metadata_1, metadata_2]
    • inline value: [numerals:: other_metadata_name]
  2. Set the metadata value of numerals to all: will index all metadata and make it available to dataview
  3. Enable "Always Process All Frontmatter" in the Numerals settings

2024-06-11 Note Properties Available Example

Numerals is able to write back to dataview values, through use of Result Insertion

⭐️ Note-wide Global Variables

Any variable name preceeded by an $ symbol will be made available to all math blocks on a page (closes #34)
2024-06-11 Numerals Global Scope Example

⭐️ Result Insertion - Store Results in Raw Text

Using the new @[...] syntax (for example: @[profit]), Numerals will insert the results of a calculation into the raw text of your notes. (closes #22)
2024-06-11 Numerals Result Insertion Example

⭐️ Greek Letter Auto-complete

  • Add greek letter auto-completion after typing :. e.g. :mu in a math block will offer μ as an auto-complete suggestion (closes #69)
  • Greek letters can be used in any variable name. They also work with subscripting when in math-tex block.

⭐️ Custom Currency Support

  • Add custom currency support. In Numerals setting, user can set a currency symbol and name. (closes #54, #52, #61)
  • Allows for example: ₿100 / day * 3 hours → 12.5 BTC if you set ₿ as the custom currency:
    2024-05-24 Numerals Custom Currency Mapping Screenshot
README file from

Numerals Obsidian Plugin

Obsidian Downloads GitHub release (latest by date) GitHub release (latest by date including pre-releases)

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.
Numerals Lemonade Stand - Side by Side
Numerals Tex Example

Features

  • Units
    • 1ft + 12in2ft
      • 20 mi / 4 hr to m/s2.235 m / s
      • 100 km/hr in mi/hr62.137 mi / hr
      • 9.81 m/s^2 * 100 kg * 40 m39.24 kJ
  • Currency
    • $1,000 * 22,000 USD
    • £10 + £0.7510.75 GBP
    • $100/hr * 3days7,200 USD
    • Set custom currencies, for example
  • Math functions
    • sqrt, sin, cos, abs, log, etc (see mathjs for full list)
  • Hex, Binary, Octal, and other bases
    • 0xff + 0b100259
    • hex(0xff + 0b100)"0x103"
  • Natural Constants
  • 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
  • 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 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 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

Numerals utilizes the mathjs 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

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
  2. TeX
  3. 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.

Numerals Render Style Side by Side

Layout

2-panes

  • Answer is shown to the right of the input with a background color and a seperator.
  • Distinctive style that seperates input from evaluated answers

Numerals 2 Panes

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

Numerals answer right

Answer Below

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

Numerals answer below

Alternating Row Colors

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

Numerals Alternating Row Style Comparison

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.

Auto-completion of Functions

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. All new Numerals features will be pushed to beta testers first.

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

Features in progress and roadmap

  • Support for mapping currency symbols to different currencies (#17)
    both $ and ¥ can be mapped to different currencies in settings
  • Style Settings support for all colors and other style options (#13)
    • Partial support added in 1.0.5
  • Result annotation, similar to Calca feature (#4)
    • Support added in 1.0.5
  • Autocompletion of functions and variable inside math code block (#15)
    • Support added in 1.0.8
  • Inline calculation for inline code blocks (#5)

Feel free to suggest additional features by creating an issue!

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

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:

Similar Plugins
info
• Similar plugins are suggested based on the common tags between the plugins.
Obsidian matrix
3 years ago by Jonas Mohr
Desmos
3 years ago by Nigecat
Embed graphs directly into your obsidian notes
Latex Suite
3 years ago by artisticat1
Make typesetting LaTeX as fast as handwriting through snippets, text expansion, and editor enhancements
Obsidian Math+
3 years ago by Oscar Capraro
This is an Obsidian plugin for taking math notes using Excalidraw.
Function Plot
3 years ago by leonhma
A obsidian.md plugin for rendering maths graphs.
Mathpad
2 years ago by Gabriele Cannata
Computer Algebra System (CAS) for Obsidian.md
Obsidian asciimath
2 years ago by widcardw
Asciimath support for Obsidian (based on asciimath-parser)
Latex Matrices
2 years ago by Daniele Susino
An obsidian plugin to create latex matrices.
MathLive
2 years ago by Dan Zilberman
The must-have plugin for math in Obsidian
Typst Renderer
2 years ago by fenjalien
Renders typst code blocks in Obsidian into images using Typst through the power of WASM!
Math Booster
2 years ago by Ryota Ushio
A powerful indexing & referencing system for theorems & equations in your Obsidian vault.
No more flickering inline math
a year ago by Ryota Ushio
No longer disturbed by flickering inline math in Obsidian.
Calctex
a year ago by Mike
An Obsidian plugin for automatic calculation of LaTeX formulas.
Auto-\displaystyle Inline Math
a year ago by Ryota Ushio
An Obsidian.md plugin to automatically make all inline maths \displaystyle.
Mathematica Plot
a year ago by Marcos Nicolau
Insert functions on Obsidian using Wolfram Mathematica!
MathLive in Editor Mode
10 months ago by MizarZh
MathLive input in editor mode.
Math Indicator Changer
8 months ago by Ori Replication
Latex Environments
4 years ago by Zach Raines
Quickly insert and change latex environments within math blocks in Obsidian.
Linter
4 years ago by Victor Tao
An Obsidian plugin that formats and styles your notes with a focus on configurability and extensibility.
Quick LaTeX
3 years ago by joeyuping
Meld Calc
3 years ago by meld-cp
IMSwitch in Math Block
17 days ago by XXM
MathType
7 days ago by slateblua
Type math faster
Command Line
3 days ago by Steven Stallion
Copy command lines from your notes to the clipboard.