note definition插件使用心得

泉客 · 2025 年11 月 10 日 10:58

用note definition有一段时间了，这中间出现了一个不大不小的问题直到今天才算是基本上解决了，把经验跟大家分享一下，希望能对沉没成本比较高的朋友有一点儿帮助。

问题：自插件版本从0.28.0更新之后的定义失效（一些朋友可能是在0.28.1或者其他版本遇到的），总之就是版本更新后插件无法解析定义文件夹。

之后我把它回退到了 0.28.0发现一切恢复正常。但是最近体感obsidian更新越来越快，既想要享受ob更新之后的便利，又害怕更新之后某个插件沦陷带来的沉没成本（比如backgroundset在更新之后失效，我比较喜欢的熊猫大佬的右键菜单分栏样式也在更新之后出了bug），总而言之，我在今天做了下整理。

我把插件0.28.0和0.28.4拖进豆包让它分析了一下各版本更新的主要内容，将出现的问题告诉它，总之，我这个代码小白总算搞明白开发者在0.28.0之后做了什么。
我们可以看到自0.28.1之后的change：

“重构了合并文件解析器以使用 LL 解析器格式。
虽然此版本已针对回归问题进行了测试，但您的某些定义文件可能会遇到问题。如果是这样，请确保您的定义文件严格遵守 README 中的规范。如果您确定解析器存在错误，请提出问题。”

现在我才弄一些明白在28.0之前，插件会解析定义文件夹内所有文件，无论是否有def-type: consolidated/atomic。而在该版本后，插件多了一个步骤，他会检测文件夹下每个定义文件的def-type验证是否正确，当我以为它会跳过验证不正确的文件，只显示验证正常的定义时，我发现它会卡主然后让整个定义文件夹失效。

“旧版本会递归解析文件夹下的所有文件（#L1352-1365）。新版本仅解析被标记为 “定义文件”（isDefFile(f) 返回 true）的文件。”

那么救赎之道就在其中，对于atomic的定义文件来说，只要检查文件夹内每个文件的def-type: atomic是否正确即可，确保每个文件都有该定义，尤其是folder notes用户的文件夹笔记，因为要求定义文件夹内的所有md文档都需要通过def验证。

而对于def-type: consolidated的文件，验证问题就有些复杂了，包括不可缺少的def-type: consolidated，还有文件的书写格式，问题在于旧版本插件的书写格式也就是通过命令来定义和更新定义的格式或许是正确的，但是通过旧版本插件命令来更新会概率性刷掉文件的元数据，而直接打开定义文件进行修改则可能会导致书写格式的错误，这就是consolidated定义文件容易出现的问题
我们可以看到其中的一个问题：

此外还有其他可能的问题我没有能完全检查出来但可能和在定义文件中使用了其他的语法有关。总之，我选择用note refactor插件吧consolidated分割为原子定义文件，然后为它们添加def-type: atomic值，解决历史遗留问题。现在用新版本的插件来生成和更新定义应该就不会造成格式不正确的问题了。

话到这里，一切…还没结束，新版本添加consolidated定义时你需要记住或者在文件名上有所标志，因为历史遗留问题，它会将部分你改为atomic但仍保留着consolidated格式的一些原子定义文件留在你的选项中，如果你将consolidated定义内容添加到了atomic文件中，那么恭喜你这个定义文件会失效，是的可喜可贺，这次不会一锅端了，当然添加到consolidated文件的定义格式要尽可能正确，如我在上图中所示的错误依然会让整个定义文件夹失效。

最后请右键拷贝你的定义文件夹到新的ob仓库中进行定义文件夹的整理，以免对主力仓库造成不可逆的伤害。

泉客 · 2025 年11 月 10 日 11:08

还有一个问题，有无插件可以将文件夹内所有md文件放入指定白板并实时检测更新和变化（我有在使用edit history插件，直接拖放文件夹会在白板放入大量 .edtz文件，而且两次拖放并不会在白板仅添加新增文件），顺带一提，Hiwords的弹窗样式贞德好看，所以它是我的了

/* 仿Hiwords风格核心样式（默认启用，无需开关） */
.definition-popover {
    background: var(--background-primary);
    border: 1px solid var(--background-modifier-border);
    border-radius: 6px;
    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.2);
    position: absolute;
    padding: 10px 14px;
    max-width: 400px;
    min-width: 200px;
    overflow: auto;
    font-size: 14px;
    animation: hiwords-fade-in 0.2s ease;
    z-index: 1000;
}

/* 标题样式 */
.definition-popover h2 {
    font-weight: 600;
    font-size: 15px;
    color: var(--text-accent);
    margin: 0 0 4px 0;
    padding-bottom: 4px;
    border-bottom: 1px solid var(--background-modifier-border);
}

/* 内容样式 */
.definition-popover [ctx="def-popup"] {
    color: var(--text-muted);
    line-height: 1.5;
    font-size: 14px;
    margin: 6px 0;
    max-height: 260px;
    overflow: auto;
}

/* 别名样式 */
.definition-popover i {
    color: var(--text-faint);
    font-size: 13px;
    display: block;
    margin-bottom: 4px;
}

/* 来源文件名样式 */
.definition-popover-filename {
    color: var(--text-faint);
    font-size: 12px;
    float: right;
    margin-top: 6px;
    opacity: 0.8;
}

/* 编辑模态框样式 */
.edit-modal-section-header {
    display: block;
    margin: 0 0 6px 0;
    font-weight: 400;
    font-size: 14px;
    color: var(--text-muted);
}

.edit-modal-aliases,
.edit-modal-textarea {
    width: 100%;
    border: 1px solid var(--background-modifier-border);
    border-radius: 4px;
    padding: 8px;
    background-color: var(--background-primary);
    color: var(--text-normal);
    font-size: 14px;
    box-sizing: border-box;
}

.edit-modal-aliases {
    height: 2em;
    margin-bottom: 20px;
}

.edit-modal-textarea {
    min-height: 100px;
    margin: 8px 0 20px 0;
    resize: vertical;
}

/* 按钮样式 */
.edit-modal-save-button-container {
    margin-top: 16px;
    display: flex;
    justify-content: space-between;
    gap: 8px;
}

.edit-modal-save-button {
    padding: 7px 14px;
    border-radius: 4px;
    background-color: var(--interactive-accent);
    color: var(--text-on-accent);
    border: none;
    font-size: 14px;
    cursor: pointer;
    transition: all 0.2s ease;
}

.edit-modal-save-button:hover {
    background-color: var(--interactive-accent-hover);
}

/* 下划线装饰样式 */
.def-decoration {
    text-decoration: underline var(--text-accent) dotted;
    -webkit-text-decoration: underline var(--text-accent) dotted;
    padding: 0 2px;
}

.def-link-decoration {
    text-decoration: underline var(--interactive-accent) dotted;
    -webkit-text-decoration: underline var(--interactive-accent) dotted;
    cursor: pointer;
    padding: 0 2px;
}

/* 动画定义 */
@keyframes hiwords-fade-in {
    from { opacity: 0; transform: translateY(5px); }
    to { opacity: 1; transform: translateY(0); }
}