Dendron 根笔记 root.md 完全指南：Vault 结构、Frontmatter 字段与发布落地页机制

知识管理知识库【免费下载链接】dendronThe personal knowledge management (PKM) tool that grows as you do!项目地址https://gitcode.com/gh_mirrors/de/dendron点击查看免费下载每个 Dendron vault 的根目录下都固定存在一个root.md文件它是整个 vault 层级树的起点、笔记解析的锚点也是发布站点时的落地页landing page。本文以 packages/plugin-core/assets/dendron-ws/vault/root.md 这份默认模板为骨架结合common-all、engine-server中的真实实现源码完整讲解 root note 的 frontmatter 字段含义、它在引擎加载流程中的特殊地位以及如何安全地自定义这份文件。读完本文你将掌握 root.md 的每一行配置背后的原理并能为自己的 vault 正确编写和维护根笔记。root.md 是什么Vault 的层级树根节点在 Dendron 中笔记按照.分隔的层级命名如dendron.ref.links这些层级会组织成一棵以root为根的树。文件 packages/plugin-core/assets/dendron-ws/vault/root.md 是 Dendron 创建新 workspace 时自动生成的默认根笔记模板其完整内容如下--- id: root title: root desc: updated: 1605266684036 created: 1595961348801 stub: false --- This is the root for your Dendron vault. If you decide to publish your entire vault, it will be your landing page. You are free to customize any part of this page except the frontmatter at the top, between the ---. ## Lookup This section contains useful links to related resources. - [Getting Started Guide](https://link.dendron.so/6b25) - [Discord](https://link.dendron.so/6b23) - [Home Page](https://wiki.dendron.so/) - [Github](https://link.dendron.so/6b24) - [Developer Docs](https://docs.dendron.so/)模板本身已经用自然语言说明了它的两个关键身份它是整个 vault 的根This is the root for your Dendron vault.当发布整个 vault 时它将成为站点的落地页If you decide to publish your entire vault, it will be your landing page。值得注意的是模板末尾的Lookup一节是官方预留的资源链接区默认放置了 Getting Started Guide、Discord、Home Page、Github、Developer Docs 等入口原模板中的这些链接均指向 Dendron 官方文档体系与社区。如果你在自己的 workspace 中保留这段内容这些链接会直接呈现在发布后的首页上可以按需替换为项目自身的文档入口。Frontmatter 字段逐项解析root.md 与普通笔记一样顶部由---包裹的 YAML frontmatter 构成。Dendron 使用正则表达式^---(.*)^---RE_FM来识别 frontmatter 块相关定义位于 packages/common-all/src/dnode.ts 的NoteUtils中。模板中的六个字段含义如下字段默认值含义与说明idroot笔记的唯一标识。对根笔记而言约定俗成固定为root与文件名保持一致titleroot笔记的显示标题会出现在树视图与页面title中desc笔记描述description留空即可发布站点时可作为页面摘要updated1605266684036上次更新时间戳Unix 毫秒。引擎写入笔记时会通过RE_FM_UPDATED_OR_CREATED/^(?beforeTimestamp(updated|created): *)(?timestamp[0-9])$/自动刷新该值created1595961348801创建时间戳Unix 毫秒与updated同属自动维护字段stubfalse是否为桩笔记。false表示这是一个真实存在的内容文件当用户只创建了子层级而未写内容时Dendron 会生成stub: true的占位笔记id、title 与 fname 的关系与普通笔记使用 UUID 作为id不同例如 test-workspace/vault/root.md 中的普通根模板使用id: b8064760-d3e6-4aac-ad62-eb44a52b01bevault 根笔记统一使用id: root。这是因为引擎对根笔记的判定完全依赖文件名而不是 idstatic isRoot(note: NotePropsMeta) { return note.fname root; }以上实现位于 packages/common-all/src/dnode.ts。也就是说只要笔记的文件名fname是root它就被视为根笔记同时getFNameDepth(root)返回0见 packages/common-all/src/dnode.ts确认根笔记位于层级深度 0其余笔记的深度按fname.split(.).length计算。为什么 root.md 不可或缺引擎加载的硬性依赖root.md 并非可有可无的装饰文件它是 vault 初始化的前置条件。在 packages/engine-server/src/drivers/file/NoteParserV2.ts 的解析流程中引擎加载一个 vault 时执行的第一个关键步骤就是定位并解析根笔记先检查深度为 1 的文件元数据是否存在若整个fileMetaDict[1]都不存在直接返回NO_ROOT_NOTE_FOUND错误在深度 1 的文件中查找fpath root.md的文件找不到同样返回NO_ROOT_NOTE_FOUND找到后以addParent: false的方式解析该文件根笔记没有父节点解析结果为空也会报NO_ROOT_NOTE_FOUND将解析出的rootNote加入内存中的笔记字典noteDicts之后解析的所有一级域名笔记domain notes都会通过DNodeUtils.addChild(rootNote, parsedNote)挂到 rootNote 之下NoteParserV2.ts从第 2 层开始逐层解析其余笔记其中root.*形式的文件被globMatch([root.*])显式排除避免把root.xxx当作普通层级笔记处理NoteParserV2.ts。这意味着删除或移动 root.md 会让整个 vault 无法被引擎识别。同时由于根笔记是层级树的最高层NoteUtils.addOrUpdateParents在重建父链时会直接忽略它if (DNodeUtils.isRoot(note)) return changed;见 packages/common-all/src/dnode.ts避免为根笔记错误地寻找父级。发布机制root.md 如何成为站点落地页模板中it will be your landing page这句话的底层逻辑可以在站点生成代码 packages/engine-server/src/topics/site.ts 的isPublished方法中找到印证static isPublished(opts: { note: NoteProps; config: DendronConfig; engine: DEngineClient; }) { const { note, config } opts; // check if note is in index const domain DNodeUtils.domainName(note.fname); const publishingConfig ConfigUtils.getPublishing(config); if ( publishingConfig.siteHierarchies[0] ! root publishingConfig.siteHierarchies.indexOf(domain) 0 ) { return false; } return this.canPublish(opts); }可以看到发布配置siteHierarchies以root作为特殊判断项当siteHierarchies[0]不是root时笔记必须属于配置的某个层级才会被发布。反过来只要你的发布配置以 root 起始即发布整个 vaultroot.md 的内容就会作为首页输出。此外该文件还通过hierarchyConfig.root相关的逻辑参与层级导航与站点目录树的构建site.ts、site.ts例如判断某个笔记是否就是索引页/根页时会使用DNodeUtils.isRoot(note)。实战如何安全地自定义你的 root.md模板明确允许你自由定制除 frontmatter 之外的任何部分You are free to customize any part of this page except the frontmatter at the top。以下给出仓库中实际存在的几种写法作为参考。1. 保留 frontmatter替换正文最安全的做法是保持六个 frontmatter 字段不动只修改正文。仓库中的教程模板 packages/plugin-core/assets/dendron-ws/tutorial/treatments/quickstart-v1/root.md 即采用此结构它与默认模板共用同一套 frontmatterid: root、title: root仅正文不同。2. 使用自定义标题test-workspace/vault/root.md 展示了另一种风格frontmatter 使用普通笔记的 UUID 式 id并将title改为Welcome to Dendron--- id: b8064760-d3e6-4aac-ad62-eb44a52b01be title: Welcome to Dendron desc: updated: 1608143370884 created: 1608143370884 --- This is the root of your dendron vault. If you decide to publish your entire vault, this will be your landing page. You are free to customize any part of this page except the frontmatter on top.注意即使id不是root只要文件名为root.md引擎仍会将其识别为根笔记——再次印证了isRoot只依赖fname。但为了与社区惯例一致、避免混淆建议保留id: root。3. 发布场景的落地页写法如果你的 vault 需要发布建议在 root.md 中写好站点首页内容例如用## 标题组织区块方便生成 TOC在Lookup一节放置项目文档、仓库、社区等入口链接让正文长度适中——首页内容会直接作为站点首页输出同时desc字段可以作为页面摘要被搜索引擎读取。4. 多 vault 工作区中的 root.md在包含多个 vault 的工作区如 test-workspace 下有vault/root.md、vault2/root.md、dependencies/localhost/local-vault/notes/root.md、dependencies/localhost/vault3/notes/root.md等多个根笔记中每个 vault 都各自拥有独立的 root.md它们分别作为各自 vault 层级树的根。引擎在NoteParserV2中按 vault 逐个执行上述先找 root.md 再挂子节点的流程因此删除任何一个 vault 的 root.md 都会导致该 vault 解析失败。常见问题排查报错NO_ROOT_NOTE_FOUND说明 vault 中缺少root.md或引擎在深度 1 未能定位到该文件。检查 vault 根目录下是否存在、文件名拼写是否为root.md参考 NoteParserV2.ts 中的定位逻辑。树视图中出现了root.xxx笔记root.*形式的文件会被解析流程显式过滤NoteParserV2.ts不要在 vault 根目录下创建root.something.md这类文件它们不会被当作正常层级笔记处理。修改 frontmatter 后时间戳被覆盖updated、created由引擎在写入时通过正则自动维护dnode.ts手工修改这两个值会在下次保存笔记时被刷新属于正常行为。小结root.md 虽只有十余行却在 Dendron 中承担三重关键职责层级树的结构起点isRoot判定、深度为 0、引擎加载的硬性前置缺失即报NO_ROOT_NOTE_FOUND、发布站点的落地页受siteHierarchies中的root配置控制。理解并善用这份模板——保持 frontmatter 稳定、按需定制正文、为多 vault 工作区中的每个 vault 保留各自的根笔记——是构建健壮、可发布 Dendron 知识库的第一步。赞分享知识管理知识库【免费下载链接】dendronThe personal knowledge management (PKM) tool that grows as you do!项目地址https://gitcode.com/gh_mirrors/de/dendron点击查看免费下载相关推荐Dendron Vault 根笔记root.md深入解析从 Landing Page 到 Frontmatter 模板渲染Dendron Vault 根笔记root.md深入解析从 Landing Page 到 Frontmatter 模板渲染 Dendron 是一个以层级知识管理知识库Dendron 记笔记实战指南Lookup 快速查找、Frontmatter 元数据与层级笔记结构的完整用法Dendron 记笔记实战指南Lookup 快速查找、Frontmatter 元数据与层级笔记结构的完整用法 本文基于 Dendron 插件自带的入门教程 知识管理知识库思源笔记插件开发实战4 条命令搭好环境并加载你的第一个插件思源笔记插件开发实战4 条命令搭好环境并加载你的第一个插件 什么时候需要写一个思源插件 你用思源笔记用了一阵子之后会发现有些操作天天在重复固定格式建文档、知识管理知识库上一篇NVIDIA显卡配置终极指南5个简单技巧快速上手官方控制面板下一篇Yii 2 学习前置条件全指南从 PHP 基础、面向对象编程到 Composer 与命令行实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考