dendron.yml 必须位于 vscode 打开的文件夹根目录才能激活插件，放错位置（如子目录）会导致 dendron 不启动；engine 未就绪、git 同步后未重载工作区、mermaid 依赖缺失等是常见问题根源。
为什么 dendron.yml 放错位置会导致 workspace 无法识别 Dendron
VSCode 启动时只会在打开的文件夹根目录（或其父级）里找 dendron.yml，找不到就当普通文件夹处理，Dendron 插件压根不激活。常见错误是把项目文档放在子目录里，比如 docs/ 下建了 dendron.yml，但 VSCode 打开的是项目根目录（./），插件就完全没反应。
- 必须确保 VSCode 打开的文件夹路径下存在
dendron.yml—— 不是子目录，就是当前工作区根目录 - 如果要用单仓库多知识库，得用
workspace.code-workspace+ 多文件夹方式，每个文件夹对应一个带dendron.yml的 Dendron workspace -
dendron.yml里workspaceRoot字段不能写成相对路径如./docs，它只接受空值或绝对路径（极少用），实际依赖的是文件位置本身
初始化后 Lookup 快捷键没反应？检查 engine 是否真正启动
Dendron 的核心功能（如创建笔记、跳转、预览）都依赖后台 engine 进程。插件装了、dendron.yml 也对了，但 Cmd/Ctrl+P → Lookup 没响应，大概率是 engine 没跑起来，而不是快捷键冲突。
- 看右下角状态栏：出现
Dendron: Ready才算正常；显示Dendron: Starting...卡住超过 10 秒，基本是初始化失败 - 打开命令面板（
Cmd/Ctrl+Shift+P），执行Dendron: Show Logs，重点查Engine started和Workspace loaded日志行 - 常见卡住原因：workspace 内有损坏的
.md文件（比如 YAML frontmatter 缺结尾---）、或notes/下存在非法命名文件（含?、#、空格）
团队协作时，git push 提交后别人 git pull 无法加载笔记？注意 workspace 和 notes 的同步边界
Dendron 本身不处理 Git 冲突，但它的文件结构让协作容易出问题：所有笔记都在 notes/ 目录，而 dendron.yml、workspace.code-workspace 等配置文件控制加载行为。拉完代码却看不到新笔记，往往不是 Git 没拉，而是本地 workspace 没刷新。
- 每次
git pull后，必须手动触发Dendron: Reload Workspace（命令面板搜），否则插件仍按旧索引服务 -
notes/下的文件名即 ID，重命名文件 = 移动笔记，Git 会当成 delete + add，可能丢失 backlink；如需改名，优先用Refactor: Rename Note命令 - 不要把
build/、.dendron/（含engine运行时缓存）提交到 Git —— 它们是生成物，不同机器重建即可
导出 HTML 或发布静态站时，publish 命令报错 Cannot find module 'remark-mermaid'
这是 Dendron 7.x+ 默认启用 Mermaid 渲染导致的典型依赖缺失。插件 UI 里点 Publish 按钮或运行 Dendron: Publish Workspace 时，若本地没装对应 remark 插件，就会直接崩在构建阶段，错误信息明确指向模块找不到。
- 进 workspace 根目录，运行：
npm install --save-dev remark-mermaid（需要本地有package.json；没有就先npm init -y） - 如果不用 Mermaid，可在
dendron.yml中关掉：publish: { enableMermaid: false } - 注意：Dendron 构建流程默认走 Node.js 环境，Windows 用户如果用 PowerShell，确保
npm命令可用，且没被杀毒软件拦截 node_modules 执行
