目录
Math Chords：在 Obsidian 中输入与规范化 数学公式
用 Obsidian 整理学术、教学或技术笔记时，公式往往不是偶尔出现的装饰，而是正文的一部分。一个推导里可能反复用到分数、上下标、希腊字母、积分、定界符和多行环境。逐字符输入 \frac、\alpha 或 \begin{aligned} 并不困难，但频率一高，注意力就会不断从“写什么”切换到“命令怎样拼”。
这正是我开发 Math Chords 的起点。我希望保留 Obsidian 中 Markdown 与 LaTeX 文本直接、透明的优点，同时减少重复结构对写作节奏的打断。项目最初借助 Cursor 完成原型，后来主要使用 OpenAI Codex 协助重构、测试和维护；功能取舍、代码审阅与发布仍由我负责。
当前版本（v0.3.4+）的 Math Chords 已不只是一个“公式快捷键”插件。它围绕两个经常同时出现的问题展开：一是更快地输入常用 LaTeX 结构，二是把从论文、AI 工具或 LaTeX 文档复制来的 \(...\)、\[...\] 安全地规范化为 Obsidian 常用的 $...$、$$...$$。前者服务于持续写作，后者处理外部内容进入笔记后的兼容问题。
用按键序列代替重复拼写
Math Chords 使用“和弦快捷键”（Chord Shortcuts）：先按一个 leader 键，再依次输入较短的按键序列。它更像编辑器中的命令前缀，而不是同时按住很多按键。
默认 leader 是 Alt+M。例如：
- 按
Alt+M，松开后再按F，插入分数结构\frac{}{}，光标停在分子位置； - 按
Alt+M，再依次按G、A，插入\alpha； - 按
Alt+M，再按D，创建一个行间公式块； - 按
Alt+M，再按Shift+E，打开行间公式环境选择器。
这些绑定参考了 LyX 数学模式的思路，但并不要求使用默认布局。leader、按键序列、插入内容、显示名称和分组都可以调整。常用组合形成肌肉记忆后，输入分数或希腊字母不必离开键盘，也不必记住每条命令的完整拼写。
如果刚开始还记不住按键，可以开启快捷键提示。按下 leader 后，提示面板会显示当前可继续输入的键。这样可以边用边熟悉，而不需要先背完一张快捷键表。
不想记快捷键时，就从公式面板开始
键盘输入适合已经熟悉的公式，公式面板则适合查找和发现。点击 Obsidian Ribbon 中的 Sigma（Σ）图标，或运行 Open formula panel 命令，就能在侧边栏浏览当前已加载的快捷公式和数学环境。
面板可以按按键、名称、LaTeX 命令或分组搜索，并使用 Obsidian 自带的 MathJax 显示预览。点击一个公式，会把它插入最近使用的 Markdown 编辑器。面板与和弦快捷键读取同一份配置，因此修改快捷键后，不需要再维护另一套公式收藏。
我更愿意把这两种入口看成同一条学习路径：先在面板中找到需要的结构，使用频率高了再记住它的按键；已经熟悉的内容直接用键盘完成。插件既不要求从第一天起背诵全部绑定，也不会让熟练用户每次都在菜单里寻找。
预览、选区和光标应当配合写作
快捷输入真正影响体验的，不只是插入了哪些字符，还包括插入之后光标在哪里。Math Chords 的模板可以标记主要编辑位置：插入分数后，光标直接进入分子；如果事先选中一段文本，模板可以把选区放进相应结构。启用“公式外自动包裹”后，在普通正文里插入数学结构时，插件会根据上下文补上行内公式定界符。
行内公式实时预览默认开启。当光标位于 $...$ 内，插件使用 Obsidian 自带的 MathJax 在编辑位置附近显示渲染结果，不额外捆绑数学渲染库。对于包含多层参数的表达式，还可以使用默认的 Alt+→ 和 Alt+← 在公式的大括号参数之间移动，减少反复用方向键定位的次数。
Math Chords 也提供行内公式和行间公式命令。非空选区会按所调用的类型进行包裹；光标位于已有公式中时，同类型命令可移除包裹。默认开启的 Smart math toggle 还允许在行内和行间公式之间转换，并避免产生嵌套的 Markdown 数学定界符。所有这些操作仍然落到普通文本上，笔记不会被转换成插件专属格式。
为多行推导准备行间公式环境
单个公式常用 $...$ 或 $$...$$ 就够了，但多行推导、矩阵和分段函数通常还需要 aligned、matrix 或 cases 等 LaTeX 环境。手动输入成对的 \begin{...} 与 \end{...} 很容易漏写一处，也会打断正在整理的推导。
Math Chords 的环境选择器默认提供 aligned、matrix、cases 和 gathered。如果光标已经在行间公式中，选定环境会包裹整个公式块内容；如果当前位置还没有行间公式，插件可以同时创建 $$...$$ 并插入环境。整个过程作为一次编辑操作提交，因此一次撤销就能完整回退。
环境列表同样可以编辑和排序。对经常撰写特定领域公式的用户，可以加入自己的环境，而不必修改插件代码。
处理从外部复制来的公式
另一类常见摩擦来自定界符差异。标准 LaTeX 文本、论文网页和 AI 工具经常使用：
\( E = mc^2 \)
\[
\int_a^b f(x)\,dx
\]Obsidian Markdown 通常使用 $...$ 和 $$...$$。逐处替换不仅费时，简单的全文查找替换还可能误伤代码示例、YAML 或已经存在的公式。
Math Chords 提供选区和当前文件两种转换命令，将 \(...\) 转为 $...$，将 \[...\] 转为 $$...$$。转换只替换定界符，公式内容、空白和换行保持不变；YAML frontmatter、围栏代码块、行内代码、HTML 注释、HTML <pre> / <code> 区域以及已有 Markdown 数学区域会被跳过。整次转换使用一个编辑事务，一次撤销即可恢复。
如果经常粘贴这类内容，也可以开启自动转换粘贴的 LaTeX 数学定界符。这个选项默认关闭：我更倾向于让会修改导入文本的自动行为由用户主动启用。其他编辑器扩展已经接管某次粘贴时，Math Chords 也不会重复处理。
这里的“规范化”有明确边界。插件不会修改公式内部语法，不会判断推导是否正确，也不会把完整 LaTeX 文档转换成 Obsidian 笔记。它解决的是定界符兼容问题，而不是数学或排版语义问题。
安装与五分钟设置
最简单的安装方式是在 Obsidian 中打开 设置 → 社区插件 → 浏览，搜索 Math Chords，安装并启用。
安装后可以按下面的顺序开始：
- 打开 设置 → Math Chords，确认 leader 为默认的
Alt+M，或改成不与现有快捷键冲突的组合。 - 在一篇 Markdown 笔记里按
Alt+M，再按F，体验分数模板与光标位置。 - 打开 Sigma 公式面板，搜索
alpha、fraction或matrix，比较点击插入与键盘输入两种方式。 - 在 设置 → 快捷键 中，按需为行内公式、行间公式或定界符转换命令分配 Obsidian 热键。插件不会为这些命令强行注册全局默认热键。
- 如果经常从外部导入公式，先对一小段选区运行转换命令，确认结果符合笔记习惯后，再决定是否开启粘贴自动转换。
默认设置已经覆盖常见输入流程，但并不要求全部启用。公式面板、提示、实时预览、大括号跳转、Smart math toggle、粘贴转换和环境包裹都可以按个人习惯调整。快捷键既可以在设置页管理，也可以通过插件目录中的 shortcuts.yaml 维护。
本地处理、兼容性与限制
Math Chords 直接通过 Obsidian 编辑器修改当前笔记，并把插件设置与快捷键配置保存在本地。当前版本没有独立账户、云端公式处理或使用数据遥测。打开 GitHub 链接、通过 Obsidian 安装或更新插件时产生的网络行为，仍由相应的应用和服务负责。
插件要求 Obsidian 1.5.0 或更高版本。由于主要交互依赖物理键盘，桌面端更适合发挥和弦快捷键的优势。不同操作系统、键盘布局和输入法可能需要重新设置 leader 或个别标点绑定。
自动化检查和受保护区域规则可以降低误改风险，但在处理重要或结构特殊的长笔记前，仍建议先转换选区，并确认撤销和版本备份可用。Math Chords 也不等同于完整的 LaTeX 编译环境：能否渲染某个宏或环境，最终取决于 Obsidian 的 Markdown 与 MathJax 支持。
开源与反馈
Math Chords 以 MIT 许可证开源。代码、详细配置和开发说明位于 GitHub 仓库，手动安装文件可从 Releases 获取。遇到可复现的问题或希望讨论新的使用场景，可以在 GitHub Issues 中反馈。
我希望 Math Chords 做的不是把公式编辑藏进一个不透明系统，而是让常用 LaTeX 文本更容易输入、检查和继续编辑：熟悉的内容交给键盘，不熟悉的内容从面板发现，外部内容则在明确边界内完成规范化。