README file from
GithubMath Chords for Obsidian
Math Chords lets you insert LaTeX formulas in Obsidian with keyboard shortcuts: press a configurable leader key, then a short key sequence to insert snippets—without typing complex LaTeX by hand. Also includes inline MathJax preview and display-math environment wrapping.
Default shortcuts are inspired by LyX math-mode bindings.
Current release: v0.1.3. See CHANGELOG.
Requires Obsidian 1.5.0+. Keyboard-heavy; desktop recommended.
Table of contents
- Features
- Installation
- Quick start
- Shortcut reference
- Display-math environment wrap
- Configuration
- Settings
- Updating shortcuts
- Project structure
- Development
- AI assistance
- License
Features
| Feature | Description |
|---|---|
| Shortcuts | Press a configurable leader key, then a key sequence to insert LaTeX snippets. |
| Caret placeholder | $$ in a command template marks where the cursor (or selection) is placed, e.g. \frac{$$}{}. |
Auto $…$ wrap |
Optional: when inserting outside math, wrap the snippet in inline math delimiters. |
| Inline live preview | While the caret is inside $…$, a floating panel above the formula renders with Obsidian's native MathJax. |
| Display-math environments | Wrap block content with \begin{…}…\end{…} via a fuzzy-search picker; inserts $$…$$ when needed. |
| Built-in math commands | Insert inline math, insert display math, wrap display math with environment (assign hotkeys in Obsidian settings). |
| YAML + UI config | Edit shortcuts.yaml or use the settings tab; changes rebuild the shortcut trie immediately. |
| Non-destructive merge | On load, missing default shortcuts are merged in; your custom key bindings are never overwritten. |
Installation
Manual
Prefer Settings → Community plugins → Browse and search for Math Chords.
To install from a release manually, download main.js, manifest.json, and styles.css from Releases into .obsidian/plugins/math-chords/ (create the folder if needed). Copy shortcuts.yaml from the repo if you want the default shortcut catalog on disk.
When installed from the community directory, Obsidian downloads main.js, manifest.json, and styles.css from the GitHub release automatically.
From source
git clone https://github.com/ichenh/obsidian-math-chords.git
cd obsidian-math-chords
npm install
npm run build
Copy main.js, manifest.json, styles.css, and shortcuts.yaml into .obsidian/plugins/math-chords/.
Quick start
- Place the caret in a Markdown note.
- Press the leader key (default
Alt+M; configurable in settings) — optionally enable the which-key popup. - Press a shortcut, e.g.
F→\frac{}{}with the cursor in the numerator. - For Greek letters:
GA→\alpha(after the leader). - For display math:
D→$$\n\n$$. - Press
Shift+E(default, after the leader) or run Wrap display math with environment to pick an environment. If the caret is not already inside$$…$$, a display block is inserted first.
Note: Shortcut tables list keys after the leader. The default leader is
Alt+M. Assign hotkeys for the built-in commands under Settings → Hotkeys (no defaults are registered).
Shortcut reference
Structures & display math
| Keys | Inserts | Description |
|---|---|---|
F |
\frac{}{} |
Fraction |
S |
\sqrt{} |
Square root |
Shift+R |
\sqrt[]{} |
Nth root |
^ |
^{} |
Superscript |
Shift+_ |
_{} |
Subscript |
D |
$$…$$ |
Display math block |
Operators & symbols
| Keys | Inserts | Description |
|---|---|---|
U |
\sum |
Sum |
I |
\int |
Integral |
Shift+I |
\int_{}^{} |
Integral with limits |
Y |
\oint |
Contour integral |
P |
\partial |
Partial derivative |
Shift+P |
\prod_{}^{} |
Product |
L |
\lim_{} |
Limit |
8 |
\infty |
Infinity |
' |
' |
Prime |
+ |
\pm |
Plus-minus |
= | |
\neq |
Not equal |
Accents
| Keys | Inserts | Description |
|---|---|---|
" |
\ddot{} |
Double dot |
H |
\hat{} |
Hat |
\ |
\grave{} |
Grave |
/ |
\acute{} |
Acute |
& |
\tilde{} |
Tilde |
- |
\bar{} |
Bar |
. |
\dot{} |
Dot |
Shift+V |
\breve{} |
Breve |
Shift+U |
\check{} |
Check |
V |
\vec{} |
Vector arrow |
_ |
\underline{} |
Underline |
B |
\overline{} |
Overline |
A W |
\widehat{} |
Wide hat |
Delimiters
| Keys | Inserts | Description |
|---|---|---|
( |
\left(\right) |
Parentheses |
[ |
\left[\right] |
Square brackets |
{ |
\left\{\right\} |
Curly brackets |
< |
\left\langle\right\rangle |
Angle brackets |
> |
\left)\right( |
Reverse parentheses |
| |
\left|\right| |
Vertical bars |
B N |
\left|\right| |
Norm |
B F |
\left\lfloor\right\rfloor |
Floor |
B E |
\left\lceil\right\rceil |
Ceiling |
Greek letters — lowercase (G + key)
| Keys | Inserts | Keys | Inserts |
|---|---|---|---|
G A |
\alpha |
G N |
\nu |
G B |
\beta |
G O |
\omega |
G C |
\chi |
G P |
\pi |
G D |
\delta |
G Q |
\vartheta |
G E |
\epsilon |
G R |
\rho |
G F |
\phi |
G S |
\sigma |
G G |
\gamma |
G T |
\tau |
G H |
\eta |
G U |
\upsilon |
G I |
\iota |
G V |
\theta |
G J |
\varphi |
G X |
\xi |
G K |
\kappa |
G Y |
\psi |
G L |
\lambda |
G Z |
\zeta |
G M |
\mu |
Greek letters — uppercase & variants (G Shift+ + key)
| Keys | Inserts | Keys | Inserts |
|---|---|---|---|
G Shift+D |
\Delta |
G Shift+S |
\Sigma |
G Shift+E |
\varepsilon |
G Shift+T |
\varsigma |
G Shift+F |
\Phi |
G Shift+U |
\Upsilon |
G Shift+G |
\Gamma |
G Shift+V |
\Theta |
G Shift+L |
\Lambda |
G Shift+O |
\Omega |
G Shift+P |
\Pi |
G Shift+X |
\Xi |
G Shift+Y |
\Psi |
Extensions
Arrows (W prefix): W R \rightarrow, W L \leftarrow, W Shift+R \Rightarrow, W Shift+L \Leftarrow, W M \mapsto
Operators (O prefix): O T \times, O C \cdot, O D \div, O E \equiv, O L \leq, O G \geq, O A \approx, O I \in, O U \cup, O Shift+U \cap, O Shift+N \nabla
Fonts (T prefix): T B \mathbf{}, T C \mathcal{}, T R \mathrm{}, T Shift+R \mathbb{}, T T \text{}
Matrices (M prefix): M P pmatrix, M B bmatrix, M C cases
The full list lives in shortcuts.yaml (101 default shortcuts).
Display-math environment wrap
With the caret inside $$…$$, or anywhere else in the note (a block is created first if needed):
- Press the configured shortcut after the leader (default
Shift+E), or run Wrap display math with environment from the command palette. - Choose an environment from the fuzzy-search list.
- The plugin wraps the entire block content (not only the selection), e.g.
$$\alpha+\beta$$→$$\begin{aligned}\alpha+\beta\end{aligned}$$
Configure environments (name / \begin{…} / \end{…}) and the trigger keys under Display-math environment wrap in Settings → Math Chords, or assign a hotkey to the command in Settings → Hotkeys.
Default environments: aligned, matrix, cases, gathered.
Configuration
shortcuts.yaml
Shortcuts are a YAML array. The leader key is global (settings), not per entry.
- keys: "F"
command: "\\frac{$$}{}"
name: "Fraction"
group: "Structures"
- keys: "G A"
command: "\\alpha"
name: "alpha"
group: "Greek"
| Field | Required | Description |
|---|---|---|
keys |
yes | Key sequence after the leader. Space-separated tokens; modifiers use + (Shift+S, G A). |
command |
yes | LaTeX snippet. Use $$ once for the caret/selection position. Write \frac not \\frac in the settings UI (auto-normalized). |
name |
no | Label in the settings table and which-key popup. |
group |
no | Grouping label in the settings table. |
Special command __DISPLAY_MATH__ inserts a $$…$$ block (used by D).
Key normalization
- Keys are canonicalized to lowercase
mod+baseorder:ctrl→alt→shift→meta. - Letters are lowercase unless
Shiftis explicit (Shift+A).
Settings
Open Settings → Math Chords. The settings UI is in English.
| Setting | Default | Description |
|---|---|---|
| Enable plugin | on | Master switch for leader shortcuts. |
| Show shortcut hints | off | Which-key panel after the leader. |
| Inline math live preview | on | MathJax preview above $…$. |
| Leader key | Alt+M |
Global prefix before shortcut keys; keys in YAML are what follows it. |
| Auto-wrap outside math | on | Auto-insert $…$ around snippets when not in math. |
| Enable environment wrap | on | Environment picker; inserts $$…$$ first when needed. |
| Environment wrap keys | Shift+E |
Keys after the leader for the picker. |
| Math environments | 4 built-ins | Editable list for the picker. |
Built-in commands (assign under Settings → Hotkeys): Insert inline math, Insert display math, Wrap display math with environment.
Shortcut management: search, add, edit, delete entries; Reload re-reads YAML; Merge defaults appends any missing built-in shortcuts without overwriting yours.
Updating shortcuts
When the plugin loads (or you click Reload or Merge defaults):
- Your existing YAML entries are kept as-is (same
keys→ same binding). - Any default shortcut whose key sequence is not yet present is appended.
- The updated file is written back to
shortcuts.yaml.
To reset completely, delete shortcuts.yaml and reload the plugin (a fresh default file will be seeded).
Regenerate the repo's default YAML from TypeScript:
npm run seed
Project structure
math-chords/ # Plugin id; install folder .obsidian/plugins/math-chords/
├── src/ # TypeScript source
│ ├── main.ts # Plugin entry
│ ├── leader.ts # Leader shortcut state machine
│ ├── defaults.ts # Default shortcut catalog
│ ├── config.ts # YAML load/save/merge
│ └── … # math, preview, settings UI, etc.
├── shortcuts.yaml # Shipped default shortcuts (101 entries)
├── styles.css # Preview & settings styles
├── manifest.json # Obsidian plugin manifest
├── esbuild.config.mjs # Build config
└── scripts/seed-yaml.cjs # Regenerate YAML from defaults.ts
Development
npm install
npm run dev # watch build
npm run build # typecheck + production bundle
npm run seed # rewrite shortcuts.yaml from src/defaults.ts
Module layout and constraints: .cursorrules.
Pull requests welcome. Run npm run build before submitting.
Releasing
- Bump
versioninmanifest.jsonandpackage.json; add the mapping toversions.json. - Update
CHANGELOG.md. - Commit, then tag with the exact version (no
vprefix), e.g.git tag 0.1.3 && git push origin 0.1.3. - The release workflow builds and attaches
main.js,manifest.json, andstyles.css.
AI assistance
This repository was bootstrapped and maintained with AI-assisted coding tools (Cursor IDE and large language models) under human review.
- Full disclosure: AI-ASSISTANCE.md
- Contributors using AI should review all output and mention it in PR descriptions.