A practical math-writing toolkit for Obsidian.
Enter LaTeX faster, normalize imported formulas safely, and keep reusable math or Markdown templates one click away.

English · 简体中文

Math Chords is an Obsidian writing toolkit built around mathematical Markdown. Its name comes from its chord-like leader shortcuts, but the plugin now covers the full path from entering a formula to reusing larger pieces of a note:

• type common LaTeX structures with short, memorable key sequences;
• browse and insert formulas from a searchable sidebar;
• save frequently used equations as titled templates and insert them by click or drag;
• store any reusable Markdown in the same template tree—definitions, derivations, callouts, tables, or complete document sections are all valid;
• normalize LaTeX delimiters copied from AI tools, papers, or TeX sources without touching protected Markdown regions;
• preview inline math, move between brace fields, toggle math wrappers, and wrap display math in environments.

Math remains the primary workflow, but templates are deliberately not limited to formulas. They store raw Markdown in plugin settings and insert that source into the active note, so a template can be a Maxwell equation block, a proof scaffold, a lab-report section, or any other repeatable Markdown content. These templates are an insertion library, not vault files and not a replacement for Obsidian's file-based core Templates feature.

Default shortcuts are inspired by LyX math-mode bindings.

Current release: v0.4.2. See CHANGELOG.

Requires Obsidian 1.5.0+. Keyboard-heavy; desktop recommended.

• What Math Chords does
• Installation
• Quick start
• Formula panel
• Shortcut reference
• Display-math environment wrap
• Configuration
• LaTeX delimiter conversion
• Settings
• Updating shortcuts
• Project structure
• Development
• AI assistance
• License

In Settings → Community plugins → Browse, search for Math Chords and install.

Obsidian's installer downloads only main.js, manifest.json, and styles.css from the plugin's GitHub release — not any other release assets. That is enough for all plugin features. Settings UI text is available immediately for the 11 bundled locales (English plus the languages listed under Settings); other Obsidian display languages fall back to English until you add locales-extras.json (see below).

Download main.js, manifest.json, styles.css, and locales-extras.json from Releases into .obsidian/plugins/math-chords/ inside your vault (create the folder if needed). Use the locales-extras.json from the same release tag as the installed plugin version. Copy shortcuts.yaml from the repo if you want the default shortcut catalog on disk.

If your Obsidian display language is not one of the 11 bundled locales, install or update this file yourself:

1. Open Releases and download locales-extras.json from the release that matches your installed plugin version (check Settings → Community plugins or manifest.json in the plugin folder).
2. Place it at .obsidian/plugins/math-chords/locales-extras.json (same folder as main.js, not inside your notes).
3. Reload Obsidian or toggle the plugin off and on.

Without this file, the plugin still works; only the Math Chords settings UI stays in English. After adding the file, the settings UI follows your Obsidian language on the next load (for any of the 61 locales shipped in that JSON).

When you update the plugin from the community directory, repeat these steps if you rely on a non-bundled locale — updates replace main.js / manifest.json / styles.css but do not refresh locales-extras.json.

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, locales-extras.json, and shortcuts.yaml into .obsidian/plugins/math-chords/.

Choose the workflow that matches what you are doing.

1. Place the caret in a Markdown note and press the leader key (default Alt+M).
2. Continue with a sequence: F inserts \frac{}{}, G A inserts \alpha, and D inserts a display-math block.
3. The $$ marker inside a configured snippet determines where the selection or caret lands. Enable shortcut hints if you want a which-key guide after pressing the leader.

1. Open the formula panel from the sigma (Σ) ribbon icon or the Open formula panel command.
2. Under Templates, use the file-plus button to create a template at the root, or the folder-plus button to organize a nested library.
3. Give the template a title and enter its Markdown body—for example a Maxwell equation system, a theorem skeleton, or a complete recurring note section.
4. Click the rendered template to insert it at the current selection, or drag its handle into the editor.

1. Select text containing \(...\) or \[...\] and run Convert LaTeX Delimiters in Selection; use the current-file command for the whole note.
2. Optionally enable conversion on paste. The converter changes delimiters only and skips frontmatter, code, HTML comments, HTML code blocks, and existing Markdown math.

For display environments, press Shift+E after the leader or run Wrap display math with environment. With only a caret inside math, the matching inline/display command removes that wrapper; with Smart math toggle enabled, the other command converts between inline and display math. A non-empty selection is always wrapped by the requested command.

Note: Shortcut tables list keys after the leader. The default leader is Alt+M. Built-in commands do not register default hotkeys; assign them under Settings → Hotkeys if desired.

Select the sigma (Σ) ribbon icon or run Open formula panel. The optional right sidebar is enabled by default; disabling it removes the ribbon action, closes the panel, and makes the command unavailable until re-enabled.

The Shortcuts section uses the same catalog as leader input. Search matches keys, names, LaTeX commands, groups, folder names, template titles, and template content. Click a rendered shortcut to insert it at the editor's current selection, or drag the card to insert it at the exact Markdown editor position under the pointer. Math Chords handles the editor drop directly, so shortcut expansion, auto-wrap, and caret placement still apply. The Math environments group reads the editable environment list from settings; aligned, matrix, cases, and gathered show representative previews and can likewise be clicked or dragged into the editor in one undoable transaction.

The Templates section is a general reusable-content library optimized for math notes:

• The folder-plus and file-plus buttons create a folder or template directly at the root. Every folder repeats both controls, so nesting has no fixed depth.
• A new folder is empty. Add templates explicitly with the clearly separated file-plus action.
• Every template has a title and a Markdown body. Obsidian renders the body—including display math, headings, lists, links, tables, callouts, and other supported Markdown—as a preview. Template and folder headers include a delete action with confirmation.
• Click the title or preview to insert the original Markdown at the current selection. Drag the title or preview into the editor to insert at the displayed drop cursor; the left handle remains dedicated to reorganizing the template tree.
• Drag any folder or template handle before or after a sibling, into another folder, or back to the root. Empty folders remain empty; moving or deleting the last template does not create a placeholder.

A template can be as focused as one Maxwell equation system or as broad as a reusable Markdown document section. Content is stored in Math Chords settings rather than as files in the vault.

Drag the left handles to reorder shortcut groups, the two main sections, template folders, or templates. Use the chevrons on the right to collapse individual sections and nodes; the summary action collapses or expands all shortcut groups, template folders, and template blocks together. Order and collapsed state persist across restarts.

Settings → Math Chords → Template management mirrors the panel tree. It supports search, root-level and nested creation, title/content editing, folder renaming, deletion, keyboard arrow reordering from a focused drag handle, and the same free drag-and-drop placement before, after, or inside folders. Shortcut management, template management, and their internal groups can all be collapsed so a long settings page remains navigable.

Panel insertion uses the same selection replacement, $$ caret marker, auto-wrap, display-math action, and cursor-placement rules as leader shortcuts. Reloading, merging, adding, editing, or deleting shortcuts refreshes open formula panels automatically. If no Markdown note is open, the plugin leaves the workspace unchanged and shows a notice.

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. Their UI previews use compact 2-by-2 matrices or a two-row cases example; insertion still places the caret in an empty environment.

The full list lives in shortcuts.yaml (102 default shortcuts).

With the caret inside $$…$$, or anywhere else in the note (a block is created first if needed):

1. Press the configured shortcut after the leader (default Shift+E), or run Wrap display math with environment from the command palette.

2. Choose an environment from the fuzzy-search list.

3. The plugin wraps the entire block content (not only the selection) and keeps delimiters and environment markers on separate lines.

   $$
   \begin{aligned}
   \alpha+\beta
   \end{aligned}
   $$

Creating a display block when needed and adding the environment are committed as one editor transaction, so one Undo reverts the command. Cancelling the picker does not modify the note.

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. On narrow settings panes, the environment table scrolls horizontally; compact order and name columns remain visible when space permits and are released on very narrow panes.

Default environments: aligned, matrix, cases, gathered.

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"

Special command __DISPLAY_MATH__ inserts a $$…$$ block (used by D).

• Keys are canonicalized to lowercase mod+base order: ctrl → alt → shift → meta.
• Letters are lowercase unless Shift is explicit (Shift+A).
• A literal + is a valid base key. For punctuation produced with Shift on the current keyboard layout, an explicit Shift+symbol binding takes precedence; otherwise the printable-symbol binding is used.

Math Chords can replace standard LaTeX math delimiters while preserving the formula contents, whitespace, and line breaks:

• \(...\) → $...$
• \[...\] → $$...$$

Use Convert LaTeX Delimiters in Selection for selected text, or Convert LaTeX Delimiters in Current File for the active Markdown note. The whole-file command reports the number of display and inline formulas converted. Each command uses one editor transaction, so one Undo reverts the complete operation.

The converter leaves delimiters unchanged inside YAML frontmatter, fenced code blocks, inline code, HTML comments, HTML <pre> / <code> blocks, and existing $...$ / $$...$$ math. Existing Markdown math is recognized using delimiter rules that distinguish it from ordinary currency text. Multiple editor selections are processed in one transaction.

Enable Automatically convert pasted LaTeX math delimiters to apply the same context-aware conversion on paste. This setting is off by default. Paste conversion does not take over an event that another editor extension has already handled.

Open Settings → Math Chords. The settings UI follows your Obsidian display language when a translation is available. On Obsidian 1.13.0 and later, individual Math Chords settings are also indexed by Obsidian's settings search.

Bundled in main.js (no extra file; works after community-plugin install): English, 简体中文, 繁體中文, 日本語, 한국어, Deutsch, Français, Español, Русский, Português (BR), Italiano.

Other official Obsidian locales (e.g. Polski, Nederlands, ไทย, العربية, English (UK), Português) require locales-extras.json in the plugin folder. Obsidian does not download that file when installing from the community directory; see Optional: extra UI languages.

Built-in commands (assign or reassign under Settings → Hotkeys): Open formula panel, Insert inline math, Insert display math, Wrap display math with environment, Convert LaTeX Delimiters in Selection, Convert LaTeX Delimiters in Current File.

No built-in command registers a default hotkey. Assign any desired bindings under Settings → Hotkeys.

• Insert inline math: wrap a non-empty selection in $…$; with only a caret, insert inline math outside math, remove an existing inline wrapper, or convert display math when Smart math toggle is on.
• Insert display math: wrap a non-empty selection in $$…$$; with only a caret, insert display math outside math, remove an existing display wrapper, or convert inline math when Smart math toggle is on.

When cross-kind conversion is disabled, invoking the other math command inside an existing block leaves the note unchanged and shows a notice instead of creating invalid nested delimiters. Converting display math to inline math removes one wrapper-adjacent line break and replaces remaining internal line breaks with spaces, because inline Markdown math cannot span lines reliably.

Shortcut management: shortcuts are grouped into compact, container-responsive sections. Each row keeps the readable name and raw LaTeX command while adding a derived MathJax preview and keycap-style sequence; narrow panes move keys and actions onto dedicated rows instead of clipping them. Visible previews render on demand so opening settings does not eagerly typeset the entire catalog. Search matches keys, names, commands, and groups without rebuilding the settings page. Add and edit operations use aligned native dialogs; deletions require confirmation. Reload re-reads YAML, and Merge defaults appends missing built-in shortcuts without overwriting yours. Formula previews are presentation-only and are never written to shortcuts.yaml.

Template management: templates use the same recursive tree and free reordering as the formula panel. Drag a handle to reorder siblings, move an item into another folder, or return it to the root; focus a handle and use the arrow keys for same-level reordering. Root and folder toolbars distinguish new folder from new template. Empty folders are allowed, and search matches template titles and Markdown bodies. Titles, source content, tree order, and collapsed state are saved in plugin settings.

When the plugin loads (or you click Reload or Merge defaults):

1. Your existing YAML entries are kept as-is (same keys → same binding).
2. Any default shortcut whose key sequence is not yet present is appended.
3. 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

math-chords/                  # Plugin id; install folder .obsidian/plugins/math-chords/
├── src/                    # TypeScript source
│   ├── main.ts             # Plugin entry
│   ├── leader.ts           # Leader shortcut state machine
│   ├── braceNav.ts         # Brace-pair navigation inside math
│   ├── delimiterConverter.ts # Pure, protected LaTeX delimiter conversion
│   ├── delimiterEditor.ts  # Obsidian editor transactions for conversion
│   ├── formulaPanel.ts      # Searchable Obsidian formula sidebar
│   ├── formulaPanelModel.ts # Pure panel grouping and filtering model
│   ├── markdownProtection.ts # Shared Markdown protected-region parser
│   ├── mathToggle.ts       # Pure inline/display toggle and conversion planning
│   ├── mathEnvPlan.ts      # Pure single-transaction environment planning
│   ├── defaults.ts         # Default shortcut catalog
│   ├── config.ts           # YAML load/save/merge
│   ├── shortcutPreviewRenderer.ts # Shared lazy MathJax preview rendering
│   ├── l10n/               # bundled locales + lazy extras loader
│   └── …                   # math, preview, settings UI, etc.
├── tests/
│   ├── unit/               # Vitest unit and regression tests
│   └── performance/        # Opt-in parser performance baselines
├── vitest.config.ts
├── shortcuts.yaml          # Shipped default shortcuts (102 entries)
├── styles.css              # Preview & settings styles
├── manifest.json           # Obsidian plugin manifest
├── scripts/                 # Generation, shared utilities, and validation
├── .github/                 # CI, release, Dependabot, and contribution templates
├── AGENTS.md                # Canonical Codex, engineering, and workflow rules
├── CONTRIBUTING.md          # Contributor workflow and submission requirements
├── SECURITY.md              # Private vulnerability reporting policy
├── CODE_OF_CONDUCT.md       # Community participation standards
├── eslint.config.mts        # Obsidian-aware lint configuration
├── .editorconfig            # Editor encoding and whitespace defaults
├── .gitattributes           # Repository line-ending and binary-file rules
└── esbuild.config.mjs       # Build config

Development requires Node.js 20.19+ or 22.12+, as declared in package.json.

npm install
npm run dev    # watch build
npm run lint   # ESLint + Obsidian plugin rules
npm run build  # typecheck + production bundle
npm test       # Vitest unit tests
npm run bench  # opt-in parser and delimiter-conversion benchmarks
npm run seed   # rewrite shortcuts.yaml from src/defaults.ts
npm run check:shortcuts # verify shortcuts.yaml matches src/defaults.ts
npm run seed:locales  # bundled TS locales + locales-extras.json from scripts/locale-catalog.json
npm run check:locales # verify locale schema and generated artifacts
npm run check:release # verify metadata, changelog, and README version references
npm run check  # complete build, test, generated-artifact, and metadata verification

Canonical Codex guidance and module, safety, generation, and release rules: AGENTS.md. The repository does not define .codex/config.toml because it currently needs no project-specific Codex runtime overrides.

Pull requests welcome. Follow CONTRIBUTING.md, run npm run check before submitting, and perform relevant manual Obsidian testing for editor-integrated behavior.

Community participation follows the Code of Conduct. Report security vulnerabilities privately using the Security Policy.

Potential future work and its design constraints are tracked in ROADMAP.md.

1. After the maintainer approves a release, update the version consistently in package.json, package-lock.json, and manifest.json; add its minimum-app mapping to versions.json.
2. Replace the Unreleased changelog section with a dated release section and create a new empty Unreleased section above it. Update the current-release line in both READMEs; the release badges track the latest GitHub release automatically.
3. Run npm run check, review the release assets, and complete the relevant manual Obsidian acceptance checks.
4. Commit, then tag with the exact version (no v prefix), e.g. git tag 0.3.0 && git push origin 0.3.0.
5. The release workflow reruns the complete verification path, builds and attaches main.js, manifest.json, styles.css, and locales-extras.json, and creates artifact attestations for every asset. Existing releases are not deleted or recreated.

This repository has used AI-assisted development tools, including Cursor and large language models, and is now maintained primarily with OpenAI Codex. These tools support tasks such as drafting, refactoring, test design, documentation, and consistency checks. Project decisions, accepted changes, and releases remain the maintainer's responsibility.

• The use of AI does not replace code review, automated checks, or relevant manual testing in Obsidian.
• Contributors remain responsible for correctness, licensing, provenance, and the protection of private or confidential information.
• Scope, verification practices, and contribution requirements: AI-ASSISTANCE.md.

MIT © CHEH Hua