Tolaria 的 Vault 文件布局扁平结构、特殊目录与递归扫描机制解析【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolariaTolaria 对笔记库Vault的目录结构不做教条式约束它递归地发现整个库中的笔记默认把新笔记放在库根目录真正的组织手段是 frontmatter 中的类型type和 wikilink 关系。本文基于 Tolaria 仓库中的参考文档 file-layout其公开版本见 site/reference/file-layout.md展开并结合 Rust 扫描器源码与相关 ADR讲清楚「什么文件会被索引、哪些目录有特殊含义、隐藏文件与 gitignore 如何影响可见性」这套机制的完整规则。核心设计哲学文件夹是可选的Tolaria 官方参考文档对文件布局的立场非常明确它不预设文件夹结构笔记可以放在任意深度的子目录里类型不来自文件夹位置而来自 frontmatter。一个典型的库结构长这样my-vault/ project-alpha.md weekly-review.md research/ source-notes.md attachments/ diagram.png source.pdf project.md person.md views/ active-projects.yml要点有三扁平库flat vault是推荐形态但不是强制形态。文档原话是「Tolaria works well with a flat vault」——文件夹是可选项对 people、projects、topics 等任何笔记类别都不是必需的文件夹存在的意义主要是与其他工具保持兼容。类型type只由 frontmatter 决定绝不会从所在文件夹推断。关系则通过字段中的 wikilink 表达。侧边栏、Properties 面板、搜索、自定义视图、邻域导航neighborhood navigation全部建立在这两类元数据之上而不是目录树之上。新笔记默认创建在库根目录组织工作交给类型和视图完成。这一哲学有完整的决策记录。ADR-0006Flat vault structure 记录了它的设计背景早期版本把笔记按类型放进project/、person/、topic/等子文件夹导致改类型必须移动文件、wikilink 解析被迫处理路径、扫描逻辑更复杂。ADR-0006 因此裁定「所有用户笔记作为扁平的.md文件存放在库根类型完全由type:frontmatter 字段决定」并带来一系列后果wikilink 解析简化为基于标题/文件名的多轮匹配、改类型只需编辑 frontmatter、为旧库提供了flatten_vault迁移命令、vault_health_check能发现散落在非保护子目录中的文件。值得注意的是ADR-0006 自己就预留了重新评估的触发条件——「当用户需要嵌套文件夹层级做非类型组织时」这正是后面 ADR-0033 出现的原因。递归索引从「只扫根目录」到「全深度扫描」文档中「It finds notes recursively across the whole vault」这句描述背后是两次演进ADR-00062026-03-15扫描被限制在根级.md文件加保护目录。ADR-0033Subfolder scanning and folder tree navigation2026-03-31放宽了上述约束用walkdir扩展 Rust 扫描器以索引所有可见子目录中的.md文件并通过新的list_vault_foldersTauri 命令把库的文件夹树暴露给侧边栏的 FOLDERS 区域。ADR-0033 明确说明「ADR-0006 的扁平库原则被放宽笔记现在可以住在子目录里」。在当前源码中这套行为可以直接验证。扫描器主体 的scan_all_files用WalkDir递归遍历整个库且follow_links(true)入口函数scan_vault在校验路径后遍历所有文件、恢复未完成的改名事务最后按修改时间倒序返回条目。隐藏规则定义在 常量与判断函数 中/// Directories hidden from user-facing vault scans. const HIDDEN_DIRS: [str] [.git, .laputa, .DS_Store]; /// Keep type definitions in their dedicated sidebar section instead of the generic folder tree. const FOLDER_TREE_EXCLUDED_DIRS: [str] [type]; fn is_hidden_dir(name: str) - bool { name.starts_with(.) || HIDDEN_DIRS.contains(name) }由此得出两条硬性规则任何以.开头的目录含.git在扫描和文件夹树中都被排除任何以.开头的文件如.gitignore、.DS_Store被scan_all_files中的显式检查跳过。文件夹树由 scan_vault_folders 单独构建它额外排除type/目录——因为类型定义文档有专属的侧边栏分区不应再出现在通用 FOLDERS 树里。测试用例 folder_and_file_kind.rs 精确验证了这两点.git、.laputa等隐藏目录不出现在树中而attachments、views保留在树中、type被过滤掉纯扁平库只有根级笔记则返回空树。特殊目录views/ 与 attachments/参考文档给出的特殊目录表是文件布局中最需要记住的部分目录用途views/保存的自定义视图saved custom views。attachments/图片和其他附件文件。这两条规则在源码层面都有对应实现views/下的.yml文件是自定义视图的存储位置例如仓库自带的演示库中就有 active-projects.yml。由于views/不是隐藏目录它会出现在文件夹树中其下的 yml 文件按文本文件处理见下一节的 fileKind 分类。attachments/存放非 Markdown 的附件。文档强调 PDF、图片和其他非 Markdown 文件「保持为普通文件」文件夹浏览会在原地显示它们而Settings 中的开关控制 PDF、图片和不受支持的文件是否出现在 All Notes 列表里。fileKind非 Markdown 文件的三分类「非 Markdown 文件保持为普通文件」这一句的实现依据是 ADR-0041fileKind field扫描器索引库中的所有文件而非仅.md每个条目携带fileKind字段markdown/text/binary前端据此决定如何渲染和打开它。classify_file_kind 给出了分类逻辑markdown扩展名为.md/.markdown。获得完整的 Tolaria 行为——frontmatter 解析、富文本编辑器、标题同步、类型系统。text扩展名命中一张约 60 项的白名单TEXT_EXTENSIONS涵盖yml、yaml、json、txt、csv、ts、py、rs、sh等无扩展名文件则按文件名匹配Makefile、Dockerfile、.gitignore等已知文本文件。这类文件以文件名为标题、无 frontmatter在原始编辑器中打开。binary其余扩展名图片、PDF 等在列表中置灰、不可点击。ADR-0041 还规定了一个关键的可见性边界非文件夹视图All Notes、类型分区、自定义视图只显示markdown条目而文件夹视图显示所有 fileKind。也就是说attachments/里的source.pdf在文件夹浏览中原地可见但是否混入 All Notes 由设置项决定——这与参考文档中「Settings controls whether PDFs, images, and unsupported files appear in All Notes」的描述一致。三种「Markdown 形态」的内容参考文档的 Special Folders 一节还澄清了三类容易放错位置的内容。它们的共同点是都是 Markdown 文件因此属于笔记不属于attachments/。白板Whiteboards是携带持久化 tldraw 数据的 Markdown 文件所以与笔记放在一起而不是放进attachments/。仓库中 ADR-0107Markdown-durable tldraw whiteboards 记录了这一持久化格式的设计。电子表格Spreadsheets同样是 Markdown 文件。一个带_display: sheet的笔记其结构是普通 frontmatter 加上 CSV 风格的正文打开时进入表格编辑器。格式细节可参考 spreadsheet-format演示库中有现成样例 tolaria-sheet-prototype-sample.md。类型定义文档Type definitions是 frontmatter 中带type: Type的 Markdown 笔记。文档特别指出新建的类型文档就是普通笔记而旧版本中放在type/旧目录里的类型文档仍然有效。这与源码中FOLDER_TREE_EXCLUDED_DIRS的注释相互印证——type/目录里的内容被刻意从通用文件夹树中剥离归入侧边栏的类型分区统一管理。.git/ 与 gitignoreGit 文件的处理边界参考文档的最后一节规则很简单如果 Vault 本身是 Git 仓库.git/归 Git 所有Tolaria 读取 Git 状态但绝不把.git/当作笔记。源码中这一点由HIDDEN_DIRS常量和WalkDir的目录过滤双重保证。除了.git/本身仓库还实现了一套更精细的「gitignore 可见性边界」ignored.rs 通过调用git check-ignore --no-index --stdin批量判断候选路径是否被 gitignore 规则命中并提供 filter_gitignored_entries / filter_gitignored_folders 两组过滤器把被忽略的条目和文件夹从扫描结果与文件夹树中剔除。该模块的测试ignored.rs 测试段覆盖了几个值得注意的边界gitignore 的否定语法ignored/*!ignored/keep.md被正确尊重Vault 位于某个父 Git 仓库内部时父仓库的 .gitignore 也会生效filters_entries_ignored_by_parent_repository过滤行为受hide_enabled开关控制——从源码结构看该开关对应一个设置项关闭时 gitignored 内容会保留keeps_ignored_entries_when_visibility_is_enabledVault 根目录是指向真实目录的符号链接时仍能正确计算相对路径filters_entries_with_real_paths_when_vault_root_is_symlinked。对用户的实际含义是被 gitignore 的内容如生成目录默认不会出现在 Tolaria 的笔记列表和文件夹树中这与「.git/归 Git、Tolaria 只读状态」的整体边界一致。用演示库验证这套规则仓库自带的演示 Vault demo-vault-v2 是文档所述布局的一个真实样本逐条对应上面讲过的规则demo-vault-v2/ 25q1.md # 根级笔记扁平库主体 person-luca-rossi.md # 人笔记在根目录不靠 person/ 文件夹 type/ # 类型定义文档目录侧边栏类型分区的数据源 person.md project.md ... views/ active-projects.yml # 保存的自定义视图 attachments/ laputa-reference.png # 二进制附件原地展示注意这里没有人/项目/主题子文件夹person-luca-rossi.md直接躺在根目录它的类别由 frontmatter 的type字段给出——这正是「Type is not inferred from folder location」的实例。规则速查问题规则依据子目录里的笔记会被索引吗会递归全深度扫描scan_all_files、ADR-0033.git/、.laputa/、点开头目录/文件一律不扫描、不进文件夹树HIDDEN_DIRStype/目录不进通用文件夹树归类型分区FOLDER_TREE_EXCLUDED_DIRS笔记类型从哪里来只从type:frontmatter不从路径ADR-0006图片/PDF 等二进制文件归类binary文件夹视图原地展示是否进 All Notes 由设置控制ADR-0041views/、attachments/保存的自定义视图 / 附件两个特殊目录参考文档白板与电子表格都是 Markdown 笔记tldraw 数据 /_display: sheet不放attachments/参考文档、ADR-0107被 gitignore 的文件经git check-ignore判定后可从可见性中剔除受设置开关控制ignored.rs一句话总结 Tolaria 的文件布局观目录只是物理位置frontmatter 才是组织结构。只要你遵守「隐藏点号目录、views/放视图、attachments/放附件、类型文档带type: Type」这几条约定其余文件放在哪一层目录都不会影响笔记的发现、类型化与关系导航。【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Tolaria 的 Vault 文件布局扁平结构、特殊目录与递归扫描机制解析【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolariaTolaria 对笔记库Vault的目录结构不做教条式约束它递归地发现整个库中的笔记默认把新笔记放在库根目录真正的组织手段是 frontmatter 中的类型type和 wikilink 关系。本文基于 Tolaria 仓库中的参考文档 file-layout其公开版本见 site/reference/file-layout.md展开并结合 Rust 扫描器源码与相关 ADR讲清楚「什么文件会被索引、哪些目录有特殊含义、隐藏文件与 gitignore 如何影响可见性」这套机制的完整规则。核心设计哲学文件夹是可选的Tolaria 官方参考文档对文件布局的立场非常明确它不预设文件夹结构笔记可以放在任意深度的子目录里类型不来自文件夹位置而来自 frontmatter。一个典型的库结构长这样my-vault/ project-alpha.md weekly-review.md research/ source-notes.md attachments/ diagram.png source.pdf project.md person.md views/ active-projects.yml要点有三扁平库flat vault是推荐形态但不是强制形态。文档原话是「Tolaria works well with a flat vault」——文件夹是可选项对 people、projects、topics 等任何笔记类别都不是必需的文件夹存在的意义主要是与其他工具保持兼容。类型type只由 frontmatter 决定绝不会从所在文件夹推断。关系则通过字段中的 wikilink 表达。侧边栏、Properties 面板、搜索、自定义视图、邻域导航neighborhood navigation全部建立在这两类元数据之上而不是目录树之上。新笔记默认创建在库根目录组织工作交给类型和视图完成。这一哲学有完整的决策记录。ADR-0006Flat vault structure 记录了它的设计背景早期版本把笔记按类型放进project/、person/、topic/等子文件夹导致改类型必须移动文件、wikilink 解析被迫处理路径、扫描逻辑更复杂。ADR-0006 因此裁定「所有用户笔记作为扁平的.md文件存放在库根类型完全由type:frontmatter 字段决定」并带来一系列后果wikilink 解析简化为基于标题/文件名的多轮匹配、改类型只需编辑 frontmatter、为旧库提供了flatten_vault迁移命令、vault_health_check能发现散落在非保护子目录中的文件。值得注意的是ADR-0006 自己就预留了重新评估的触发条件——「当用户需要嵌套文件夹层级做非类型组织时」这正是后面 ADR-0033 出现的原因。递归索引从「只扫根目录」到「全深度扫描」文档中「It finds notes recursively across the whole vault」这句描述背后是两次演进ADR-00062026-03-15扫描被限制在根级.md文件加保护目录。ADR-0033Subfolder scanning and folder tree navigation2026-03-31放宽了上述约束用walkdir扩展 Rust 扫描器以索引所有可见子目录中的.md文件并通过新的list_vault_foldersTauri 命令把库的文件夹树暴露给侧边栏的 FOLDERS 区域。ADR-0033 明确说明「ADR-0006 的扁平库原则被放宽笔记现在可以住在子目录里」。在当前源码中这套行为可以直接验证。扫描器主体 的scan_all_files用WalkDir递归遍历整个库且follow_links(true)入口函数scan_vault在校验路径后遍历所有文件、恢复未完成的改名事务最后按修改时间倒序返回条目。隐藏规则定义在 常量与判断函数 中/// Directories hidden from user-facing vault scans. const HIDDEN_DIRS: [str] [.git, .laputa, .DS_Store]; /// Keep type definitions in their dedicated sidebar section instead of the generic folder tree. const FOLDER_TREE_EXCLUDED_DIRS: [str] [type]; fn is_hidden_dir(name: str) - bool { name.starts_with(.) || HIDDEN_DIRS.contains(name) }由此得出两条硬性规则任何以.开头的目录含.git在扫描和文件夹树中都被排除任何以.开头的文件如.gitignore、.DS_Store被scan_all_files中的显式检查跳过。文件夹树由 scan_vault_folders 单独构建它额外排除type/目录——因为类型定义文档有专属的侧边栏分区不应再出现在通用 FOLDERS 树里。测试用例 folder_and_file_kind.rs 精确验证了这两点.git、.laputa等隐藏目录不出现在树中而attachments、views保留在树中、type被过滤掉纯扁平库只有根级笔记则返回空树。特殊目录views/ 与 attachments/参考文档给出的特殊目录表是文件布局中最需要记住的部分目录用途views/保存的自定义视图saved custom views。attachments/图片和其他附件文件。这两条规则在源码层面都有对应实现views/下的.yml文件是自定义视图的存储位置例如仓库自带的演示库中就有 active-projects.yml。由于views/不是隐藏目录它会出现在文件夹树中其下的 yml 文件按文本文件处理见下一节的 fileKind 分类。attachments/存放非 Markdown 的附件。文档强调 PDF、图片和其他非 Markdown 文件「保持为普通文件」文件夹浏览会在原地显示它们而Settings 中的开关控制 PDF、图片和不受支持的文件是否出现在 All Notes 列表里。fileKind非 Markdown 文件的三分类「非 Markdown 文件保持为普通文件」这一句的实现依据是 ADR-0041fileKind field扫描器索引库中的所有文件而非仅.md每个条目携带fileKind字段markdown/text/binary前端据此决定如何渲染和打开它。classify_file_kind 给出了分类逻辑markdown扩展名为.md/.markdown。获得完整的 Tolaria 行为——frontmatter 解析、富文本编辑器、标题同步、类型系统。text扩展名命中一张约 60 项的白名单TEXT_EXTENSIONS涵盖yml、yaml、json、txt、csv、ts、py、rs、sh等无扩展名文件则按文件名匹配Makefile、Dockerfile、.gitignore等已知文本文件。这类文件以文件名为标题、无 frontmatter在原始编辑器中打开。binary其余扩展名图片、PDF 等在列表中置灰、不可点击。ADR-0041 还规定了一个关键的可见性边界非文件夹视图All Notes、类型分区、自定义视图只显示markdown条目而文件夹视图显示所有 fileKind。也就是说attachments/里的source.pdf在文件夹浏览中原地可见但是否混入 All Notes 由设置项决定——这与参考文档中「Settings controls whether PDFs, images, and unsupported files appear in All Notes」的描述一致。三种「Markdown 形态」的内容参考文档的 Special Folders 一节还澄清了三类容易放错位置的内容。它们的共同点是都是 Markdown 文件因此属于笔记不属于attachments/。白板Whiteboards是携带持久化 tldraw 数据的 Markdown 文件所以与笔记放在一起而不是放进attachments/。仓库中 ADR-0107Markdown-durable tldraw whiteboards 记录了这一持久化格式的设计。电子表格Spreadsheets同样是 Markdown 文件。一个带_display: sheet的笔记其结构是普通 frontmatter 加上 CSV 风格的正文打开时进入表格编辑器。格式细节可参考 spreadsheet-format演示库中有现成样例 tolaria-sheet-prototype-sample.md。类型定义文档Type definitions是 frontmatter 中带type: Type的 Markdown 笔记。文档特别指出新建的类型文档就是普通笔记而旧版本中放在type/旧目录里的类型文档仍然有效。这与源码中FOLDER_TREE_EXCLUDED_DIRS的注释相互印证——type/目录里的内容被刻意从通用文件夹树中剥离归入侧边栏的类型分区统一管理。.git/ 与 gitignoreGit 文件的处理边界参考文档的最后一节规则很简单如果 Vault 本身是 Git 仓库.git/归 Git 所有Tolaria 读取 Git 状态但绝不把.git/当作笔记。源码中这一点由HIDDEN_DIRS常量和WalkDir的目录过滤双重保证。除了.git/本身仓库还实现了一套更精细的「gitignore 可见性边界」ignored.rs 通过调用git check-ignore --no-index --stdin批量判断候选路径是否被 gitignore 规则命中并提供 filter_gitignored_entries / filter_gitignored_folders 两组过滤器把被忽略的条目和文件夹从扫描结果与文件夹树中剔除。该模块的测试ignored.rs 测试段覆盖了几个值得注意的边界gitignore 的否定语法ignored/*!ignored/keep.md被正确尊重Vault 位于某个父 Git 仓库内部时父仓库的 .gitignore 也会生效filters_entries_ignored_by_parent_repository过滤行为受hide_enabled开关控制——从源码结构看该开关对应一个设置项关闭时 gitignored 内容会保留keeps_ignored_entries_when_visibility_is_enabledVault 根目录是指向真实目录的符号链接时仍能正确计算相对路径filters_entries_with_real_paths_when_vault_root_is_symlinked。对用户的实际含义是被 gitignore 的内容如生成目录默认不会出现在 Tolaria 的笔记列表和文件夹树中这与「.git/归 Git、Tolaria 只读状态」的整体边界一致。用演示库验证这套规则仓库自带的演示 Vault demo-vault-v2 是文档所述布局的一个真实样本逐条对应上面讲过的规则demo-vault-v2/ 25q1.md # 根级笔记扁平库主体 person-luca-rossi.md # 人笔记在根目录不靠 person/ 文件夹 type/ # 类型定义文档目录侧边栏类型分区的数据源 person.md project.md ... views/ active-projects.yml # 保存的自定义视图 attachments/ laputa-reference.png # 二进制附件原地展示注意这里没有人/项目/主题子文件夹person-luca-rossi.md直接躺在根目录它的类别由 frontmatter 的type字段给出——这正是「Type is not inferred from folder location」的实例。规则速查问题规则依据子目录里的笔记会被索引吗会递归全深度扫描scan_all_files、ADR-0033.git/、.laputa/、点开头目录/文件一律不扫描、不进文件夹树HIDDEN_DIRStype/目录不进通用文件夹树归类型分区FOLDER_TREE_EXCLUDED_DIRS笔记类型从哪里来只从type:frontmatter不从路径ADR-0006图片/PDF 等二进制文件归类binary文件夹视图原地展示是否进 All Notes 由设置控制ADR-0041views/、attachments/保存的自定义视图 / 附件两个特殊目录参考文档白板与电子表格都是 Markdown 笔记tldraw 数据 /_display: sheet不放attachments/参考文档、ADR-0107被 gitignore 的文件经git check-ignore判定后可从可见性中剔除受设置开关控制ignored.rs一句话总结 Tolaria 的文件布局观目录只是物理位置frontmatter 才是组织结构。只要你遵守「隐藏点号目录、views/放视图、attachments/放附件、类型文档带type: Type」这几条约定其余文件放在哪一层目录都不会影响笔记的发现、类型化与关系导航。【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
