AsciiMath Blocks

Write AsciiMath in Obsidian's standard $...$ expressions and $$...$$ blocks. The plugin renders inline and display math using Obsidian's fonts and theme, with support for native LaTeX and custom symbols.

The radius is $sqrt(x^2 + y^2)$.

$$
(a+b)/(c+d)
$$

Installation

1. Extract the plugin ZIP and copy the asciimath-blocks folder into <vault>/.obsidian/plugins/. The folder should contain main.js, manifest.json, and styles.css.
2. Restart Obsidian.
3. Open Settings → Community plugins, enable community plugins if needed, then enable AsciiMath Blocks.

You can also build the plugin from source and copy those three files into the same folder. Requires Obsidian 1.9.10 or newer. Mobile has not been tested.

Writing and editing math

Use $...$ for inline math and $$...$$ for display math. In Live Preview and Source mode, inactive expressions are rendered automatically. Click an expression or move the cursor into it to edit its source. Inline math shows its source while being edited; display blocks keep an updating preview below the closing $$. Reading view always shows rendered math.

Rendering does not modify notes or undo history. Other text in Source mode keeps its usual formatting.

In an AsciiMath display block, leave an empty line between expressions to render them on separate rows:

$$
[(3,10),(6,-1)][(0),(1)]

= [(10),(-1)]
$$

Single line breaks are treated as spaces. Blank lines inside matrix brackets, grouping brackets, or text labels do not start a new row. Native LaTeX keeps its usual line-break syntax.

AsciiMath examples

Parentheses group expressions. Unicode math letters and minus signs are also supported. See AsciiMath for the full syntax.

Native LaTeX

LaTeX works in the same delimiters:

$$
\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

An expression containing a LaTeX command such as \frac, \sqrt, or \alpha is rendered entirely as LaTeX. Expressions without LaTeX commands use AsciiMath by default, including custom symbols. Quoted AsciiMath labels stay text.

For ambiguous syntax, use \displaystyle{...} in a block or \textstyle{...} inline to force LaTeX. For example, a/b is an AsciiMath fraction, while \displaystyle{a/b} keeps the LaTeX slash.

Custom symbols

Open Settings → AsciiMath Blocks, enter one mapping per line, and click Save symbols:

cross = \text{ x }

Then $a cross b$ inserts the mapped LaTeX between the variables. Open previews update after saving. Mappings are stored per vault and apply to AsciiMath rendering and the LaTeX conversion commands.

Names are case-sensitive and use letters and numbers, starting with a letter. Values are standard LaTeX without dollar delimiters. Existing AsciiMath functions such as sqrt keep their meaning. Quoted labels such as "cross" remain text. Delete a mapping's line and save to remove it; save an empty box to restore the default symbols.

Convert to LaTeX

Open the command palette and search for AsciiMath Blocks:

• Convert current math to LaTeX converts the expression containing the cursor, or a single selected expression.
• Convert all math in note to LaTeX converts every complete AsciiMath expression in the current note.

The commands preserve dollar delimiters, skip code examples and existing LaTeX, and support undo. A whole-note conversion is one undo step. Commands appear only when there is AsciiMath to convert.

Converted expressions include custom symbol definitions and use standard LaTeX style commands. They continue rendering if a mapping changes or the plugin is disabled. Without conversion, notes containing AsciiMath require this plugin to render correctly.

Development

Use Node.js 22.18 or newer and a separate development vault.

npm ci
npm run dev     # Watch and rebuild
npm run build   # Type-check and bundle
npm test        # Run tests

Copy main.js, manifest.json, and styles.css into the development vault's plugin folder. Disable and re-enable the plugin after rebuilding.

The plugin runs locally and makes no network requests. It uses Obsidian's MathJax renderer; plugins that replace MathJax may conflict with it.

License

The plugin is MIT licensed. AsciiMath conversion uses asciimath2tex by Christian Lawson-Perfect, licensed under Apache 2.0. Its attribution and license are included in the bundled plugin.