Better Heading Links

简体中文 | English

让 Obsidian 的标题链接在重命名、剪切和重构后依然保持可用。

在知识管理里，我们经常会遇到一个很现实的问题：长篇笔记虽然更容易持续写作和维护，但一旦大量使用 [[文件名#一级标题#二级标题]] 这种精确链接，后续只要改标题、调层级、剪切内容到别的笔记，链接就很容易断掉。

Better Heading Links 就是为这个场景做的。它会在后台跟踪标题路径变化，并自动修复受影响的内部链接。

核心能力

标题重命名自动修复

• 自动更新指向标题的普通链接
• 自动更新带别名的标题链接
• 支持多层路径，例如 [[笔记#父标题#子标题]]

剪切 / 粘贴移动自动修复

• 把一个标题小节剪切到另一篇笔记后，相关链接会自动改到新文件
• 会尽量保留原本的路径形式，而不是强行展开成更长的标题链
• 支持多层标题路径一起迁移

手动修复兜底

• 提供 Repair links in current file 命令
• 当自动修复没有覆盖到某些边角情况时，可以对当前笔记再做一次修复

面向大量链接的优化

• 使用增量索引和重定向压缩来减少重复扫描
• 适合做较大规模的笔记重构
• 仓库内自带压力测试样例

适合谁

• 大量使用 #标题 或 #父标题#子标题 精确定位的人
• 经常重构长笔记结构的人
• 希望保留长文写作体验，但又不想放弃精细化双链的人

解决的问题

场景	Obsidian 原生表现	Better Heading Links
重命名标题	可能漏改或失效	自动更新相关引用
跨文件移动标题	链接容易断开	自动改到新文件
多层标题路径变化	[[#A#B]] 容易失效	重新计算并修复路径
大规模内容重组	需要手动清理	提供批量修复能力

开发

安装依赖：

npm install

构建插件：

npm run build

测试内容

仓库里包含一套压力测试用例，位置在：

• test-vault/stress-test/

目前内置两种大规模场景：

• 重命名压力测试：80 个反链文件，预计同时更新 400 条链接
• 移动压力测试：80 个反链文件，预计同时更新 400 条链接

重新生成压力测试数据：

npm run stress:reset

本地测试 Vault 同步

把当前构建同步到本地测试 vault 的插件目录：

powershell -ExecutionPolicy Bypass -File .\sync-test-vault.ps1

仓库结构

• src/：插件源码
• main.js：当前构建产物
• scripts/generate-stress-test.mjs：压力测试生成脚本
• test-vault/stress-test/：压力测试样例

致谢

本项目基于 obsidian-persistent-links 的思路与代码演进而来，并遵循其 MIT 许可证要求保留相应署名。