Tolaria Frontmatter 字段全解析从 type/status 到系统下划线属性的完整指南【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolariaFrontmatter 是 Tolaria 这个 Markdown 知识库桌面应用中每个笔记的元数据头它决定了笔记的实体类型、生命周期状态、图标、关系网络、编辑器宽度乃至表格Sheet的呈现方式。本文以 frontmatter-fields.md 为骨架结合仓库源码与 ADR 决策记录系统梳理全部内置字段、系统保留字段_前缀的语义与用法并给出可直接复制的 Frontmatter 示例。读完你将掌握如何为一篇笔记配置类型、状态、图标与关系如何在 raw 模式下读写被 UI 隐藏的系统字段以及 Tolaria 约定优于模式conventions instead of a required schema的设计哲学。核心思想约定优于模式Tolaria 对 Frontmatter 不强制任何固定 schema。任何笔记都可以只写一个# 标题也可以带上任意数量的自定义字段系统通过命名约定如下划线前缀、wikilink 值、type:键名而非硬编码列表来识别字段语义。这一点在源码中有明确体现systemMetadata.ts 将系统元数据按别名分组归一化而 ADR 0010-dynamic-wikilink-relationship-detection.md 记录了关系字段动态探测的决策Rust 解析器扫描所有 Frontmatter 键凡值包含[[wikilink]]的字段都会被捕获进relationships映射无需任何配置或硬编码名单。这意味着用户新增关系类型、自定义属性都不需要改代码——正是 convention over configuration。内置字段总览下表完整对应原文档中的字段表字段含义type笔记的实体类型entity typestatus生命周期状态lifecycle stateicon单笔记图标per-note iconurl外部 URLdate单个日期belongs_to父级关系parent relationshiprelated_to横向/同级关系lateral relationshiphas包含关系contained relationship_width单笔记编辑器宽度覆盖值_display显示模式文本笔记可省略表格笔记用sheet_icon、_color类型或笔记的外观元数据。_icon取值支持 kebab-case 的 Phosphor 图标名、emoji 或 HTTP(S) 图片 URL_sidebar_label、_order类型的侧边栏标签与排序_pinned_properties某类型笔记在编辑器内联工具栏中固定的属性_list_properties_display某类型笔记在笔记列表中展示为芯片chips或列的属性_sheet表格笔记的呈现元数据如网格设置、列宽、行高、单元格格式type实体类型的规范字段type是 Tolaria 中识别实体类型的规范 Frontmatter 键。ADR 0025-type-field-canonical.md 记录了它的历史早期使用自然语言风格Is A: Project由于空格与冒号解析不便、且非标准 YAML 惯例最终统一为type:。当前实现中新笔记一律写type: Project旧笔记的Is A:作为遗留别名继续被读取Rust 解析器先查type:再回退Is A:内部字段名仍为isA兼容旧代码相关归一化逻辑可见 systemMetadata.ts 中的type: [type, is_a, is a]别名分组运行 Repair Vault 可将遗留Is A:迁移为type:。示例来自 demo-vault-v2/25q2-laputa-v2.md--- type: Project aliases: - [[Laputa App V2]] belongs_to: [[25q2]] owner: [[person-luca-rossi]] status: Active related_to: - [[laputa-qa-reference]] ---类型文档本身也遵循同一约定见 demo-vault-v2/type/project.md--- type: Type icon: rocket color: blue sidebar label: Projects ---status生命周期状态status表示笔记的生命周期状态值由用户/类型约定如Active、Archived、Backlog等Tolaria 不做枚举限制。上例中项目笔记status: Active即为典型用法。状态可配合视图过滤条件使用具体过滤语法见 view-filters.md。icon单笔记图标icon允许为单篇笔记设置独立图标。ADR 0049-per-note-icon-property.md 说明了它的解析规则resolveNoteIcon()返回一个判别联合按优先级识别为none空值、emoji通过isEmoji()判断、imageHTTP(S) URL或phosphor注册的 Phosphor 图标名。NoteTitleIcon组件据类型渲染span、img或 Phosphor SVG。注意icon与系统字段_icon存在别名归一化关系——systemMetadata.ts 中_icon: [_icon, icon]即两者按同一规范键处理。单笔记的icon/_icon会覆盖其类型继承的图标。url、date 与自定义字段url记录外部链接纯数据字段无特殊 UI 行为。date单一日期值配合 ADR 0039-git-history-for-note-dates.md 等机制使用。自定义字段任意 YAML 键均可自由添加。关键规则如果某字段的值包含[[wikilink]]Tolaria 就会把它当作关系字段处理见下文关系字段并在 Inspector 的关系面板自动展示。关系字段belongs_to、related_to、hasTolaria 支持任意关系语义内置三个约定字段belongs_to父级关系如项目属于季度belongs_to: [[25q2]]related_to横向/同级关系如项目关联参考笔记related_to: [[laputa-qa-reference]]has包含关系表示拥有/包含的下级条目。这三个字段在 systemMetadata.ts 中登记了别名belongs_to/belongs to、related_to/related to。但根据 ADR 0010它们并不特权化——真正决定关系识别的是值是否为 wikilink。任何自定义字段如owner: [[person-luca-rossi]]、depends_on: [[xxx]]都会自动进入关系图谱在 RelationshipsPanel.tsx 中统一呈现。系统字段下划线保留命名空间以_开头的字段为系统保留字段承载应用内部行为并默认从标准属性编辑面板隐藏。它们依然是普通 YAML因此可以在 raw 模式下检查或修改。系统字段的嵌套子键同样归系统所有——例如_sheet.cells.B6.num_fmt属于表格编辑器不应作为普通用户属性出现。规范化canonicalization与别名systemMetadata.ts 定义了完整的归一化体系normalizePropertyKey去除首尾空白、转小写、空白转下划线canonicalFrontmatterKey将别名归一到规范键如sidebar label→_sidebar_labelisSystemMetadataKey键以_开头或命中系统别名即判定为系统元数据canonicalFrontmatterWriteKey写入时强制使用规范键CANONICAL_WRITE_KEYS覆盖type及全部系统键。这意味着读取时兼容各种历史写法大小写不敏感、支持sidebar label带空格等写入时则统一落盘为规范键。外观与侧边栏_icon、_color、_sidebar_label、_order_icon类型或笔记的图标。取值三种形态——kebab-case 的 Phosphor 图标名如rocket、folders见 demo 类型文档、emoji如、或 HTTP(S) 图片 URL。ADR 0049 指出图标解析器在类型文档与笔记间共享。_color类型外观颜色如blue、amber。当前主要作用于类型级ADR 0049 提到若未来支持单笔记颜色可复用同一解析模式。_sidebar_label类型在侧边栏显示的标签如 Projects、Areas。_order类型在侧边栏的排序位置。demo 中 demo-vault-v2/type/area.md 即为完整示例--- type: Type icon: folders color: amber sidebar label: Areas ---注意这里使用了带空格的别名sidebar label——读取时会被归一为_sidebar_label。编辑器与列表_width、_display、_pinned_properties、_list_properties_display_width单笔记编辑器宽度覆盖值per-note editor width override。_display显示模式。文本笔记省略该字段表格笔记写sheet与 ADR 0134-sheet-nodes-with-plain-text-workbook-storage.md 的 Sheet 节点方案呼应。_pinned_properties某类型笔记在编辑器内联栏inline bar中固定的属性集合。_list_properties_display某类型笔记在笔记列表中作为芯片或列展示的属性集合。这两个字段将类型的属性呈现策略声明在类型文档 Frontmatter 中由noteListHooks.ts等列表逻辑消费。表格呈现_sheet_sheet承载 Sheet 笔记的呈现元数据网格设置、列宽、行高、单元格格式等。它的嵌套结构整体归系统所有例如_sheet.cells.B6.num_fmt是单元格格式数字格式用户在普通属性面板中不应编辑如需调整应进入 raw 模式。相关序列化契约见 spreadsheet-format.md 与 spreadsheet-functions.md。更多系统元数据除原文档列出的字段外systemMetadata.ts 与 ADR 0008-underscore-system-properties.md 还登记了以下系统键供 raw 模式使用规范键说明写入方_archived归档标记兼容旧键Archived/archived归档操作_trashed回收站标记删除操作_trashed_at删除时间删除操作_favorite收藏标记收藏切换_favorite_index收藏排序收藏重排_organized已整理标记整理流程_sort排序元数据排序操作写入规则一律使用_前缀的规范键读取规则兼容规范键与遗留键大小写不敏感但不做读取时重写。自定义字段与动态关系最灵活的扩展点自定义字段是 Tolaria 最大的扩展空间写任意 YAML 键如tier: 1st见 demo-vault-v2/person-luca-rossi.md只要值包含[[wikilink]]字段即成为关系自动出现在关系面板关系面板、视图过滤view-filters.md、笔记列表列展示_list_properties_display都可以直接使用这些字段无需注册。实战模板一张完整的 Frontmatter综合以上规则一个信息密度较高的笔记 Frontmatter 模板如下--- type: Project status: Active icon: rocket url: https://example.com/docs date: 2026-09-01 belongs_to: [[25q3]] related_to: - [[laputa-qa-reference]] has: - [[task-onboarding]] owner: [[person-luca-rossi]] tier: 1st _width: 90 _display: text _icon: rocket _color: blue _sidebar_label: Projects _order: 1 _pinned_properties: - status - owner _list_properties_display: - status - owner ---要点回顾无_前缀的字段含owner、tier是普通/自定义属性其中含 wikilink 的自动成为关系_前缀字段是系统保留标准属性面板隐藏raw 模式可改写入用规范键读取兼容别名如sidebar label等价于_sidebar_label类型文档与笔记共用同一套 Frontmatter 约定仅以type: Type区分角色。常见问题Q1为什么我在属性面板看不到_favorite、_width这类字段因为以_开头的字段被解析器过滤不进入标准属性编辑 UIADR 0008。这是刻意设计防止内部字段干扰用户编辑。需要修改时切换到 raw 编辑器直接改 YAML 即可。Q2icon和_icon有什么区别两者按同一规范键归一化。_icon是系统字段的规范形态icon是其别名写入时统一落盘为规范键。功能上单笔记的图标会覆盖其类型的图标。Q3我想新增一种关系需要改代码吗不需要。任意字段只要值含[[wikilink]]就会被动态识别为关系ADR 0010Inspector 关系面板自动收录。Q4遗留笔记用了Is A:怎么办读取兼容解析器会回退识别。运行 Repair Vault 可批量迁移为type:ADR 0025。延伸阅读视图过滤表达式view-filters.md自定义视图引擎0040-custom-views-yml-filter-engine.md表格序列化格式spreadsheet-format.md、spreadsheet-functions.md关系机制相关 ADR0010-dynamic-wikilink-relationship-detection.md、0035-path-suffix-wikilink-resolution.md系统属性约定0008-underscore-system-properties.md图标解析实现noteIcon.ts对应resolveNoteIcon路径以仓库实际为准规范化实现systemMetadata.ts【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Tolaria Frontmatter 字段全解析：从 type/status 到系统下划线属性的完整指南
Tolaria Frontmatter 字段全解析从 type/status 到系统下划线属性的完整指南【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolariaFrontmatter 是 Tolaria 这个 Markdown 知识库桌面应用中每个笔记的元数据头它决定了笔记的实体类型、生命周期状态、图标、关系网络、编辑器宽度乃至表格Sheet的呈现方式。本文以 frontmatter-fields.md 为骨架结合仓库源码与 ADR 决策记录系统梳理全部内置字段、系统保留字段_前缀的语义与用法并给出可直接复制的 Frontmatter 示例。读完你将掌握如何为一篇笔记配置类型、状态、图标与关系如何在 raw 模式下读写被 UI 隐藏的系统字段以及 Tolaria 约定优于模式conventions instead of a required schema的设计哲学。核心思想约定优于模式Tolaria 对 Frontmatter 不强制任何固定 schema。任何笔记都可以只写一个# 标题也可以带上任意数量的自定义字段系统通过命名约定如下划线前缀、wikilink 值、type:键名而非硬编码列表来识别字段语义。这一点在源码中有明确体现systemMetadata.ts 将系统元数据按别名分组归一化而 ADR 0010-dynamic-wikilink-relationship-detection.md 记录了关系字段动态探测的决策Rust 解析器扫描所有 Frontmatter 键凡值包含[[wikilink]]的字段都会被捕获进relationships映射无需任何配置或硬编码名单。这意味着用户新增关系类型、自定义属性都不需要改代码——正是 convention over configuration。内置字段总览下表完整对应原文档中的字段表字段含义type笔记的实体类型entity typestatus生命周期状态lifecycle stateicon单笔记图标per-note iconurl外部 URLdate单个日期belongs_to父级关系parent relationshiprelated_to横向/同级关系lateral relationshiphas包含关系contained relationship_width单笔记编辑器宽度覆盖值_display显示模式文本笔记可省略表格笔记用sheet_icon、_color类型或笔记的外观元数据。_icon取值支持 kebab-case 的 Phosphor 图标名、emoji 或 HTTP(S) 图片 URL_sidebar_label、_order类型的侧边栏标签与排序_pinned_properties某类型笔记在编辑器内联工具栏中固定的属性_list_properties_display某类型笔记在笔记列表中展示为芯片chips或列的属性_sheet表格笔记的呈现元数据如网格设置、列宽、行高、单元格格式type实体类型的规范字段type是 Tolaria 中识别实体类型的规范 Frontmatter 键。ADR 0025-type-field-canonical.md 记录了它的历史早期使用自然语言风格Is A: Project由于空格与冒号解析不便、且非标准 YAML 惯例最终统一为type:。当前实现中新笔记一律写type: Project旧笔记的Is A:作为遗留别名继续被读取Rust 解析器先查type:再回退Is A:内部字段名仍为isA兼容旧代码相关归一化逻辑可见 systemMetadata.ts 中的type: [type, is_a, is a]别名分组运行 Repair Vault 可将遗留Is A:迁移为type:。示例来自 demo-vault-v2/25q2-laputa-v2.md--- type: Project aliases: - [[Laputa App V2]] belongs_to: [[25q2]] owner: [[person-luca-rossi]] status: Active related_to: - [[laputa-qa-reference]] ---类型文档本身也遵循同一约定见 demo-vault-v2/type/project.md--- type: Type icon: rocket color: blue sidebar label: Projects ---status生命周期状态status表示笔记的生命周期状态值由用户/类型约定如Active、Archived、Backlog等Tolaria 不做枚举限制。上例中项目笔记status: Active即为典型用法。状态可配合视图过滤条件使用具体过滤语法见 view-filters.md。icon单笔记图标icon允许为单篇笔记设置独立图标。ADR 0049-per-note-icon-property.md 说明了它的解析规则resolveNoteIcon()返回一个判别联合按优先级识别为none空值、emoji通过isEmoji()判断、imageHTTP(S) URL或phosphor注册的 Phosphor 图标名。NoteTitleIcon组件据类型渲染span、img或 Phosphor SVG。注意icon与系统字段_icon存在别名归一化关系——systemMetadata.ts 中_icon: [_icon, icon]即两者按同一规范键处理。单笔记的icon/_icon会覆盖其类型继承的图标。url、date 与自定义字段url记录外部链接纯数据字段无特殊 UI 行为。date单一日期值配合 ADR 0039-git-history-for-note-dates.md 等机制使用。自定义字段任意 YAML 键均可自由添加。关键规则如果某字段的值包含[[wikilink]]Tolaria 就会把它当作关系字段处理见下文关系字段并在 Inspector 的关系面板自动展示。关系字段belongs_to、related_to、hasTolaria 支持任意关系语义内置三个约定字段belongs_to父级关系如项目属于季度belongs_to: [[25q2]]related_to横向/同级关系如项目关联参考笔记related_to: [[laputa-qa-reference]]has包含关系表示拥有/包含的下级条目。这三个字段在 systemMetadata.ts 中登记了别名belongs_to/belongs to、related_to/related to。但根据 ADR 0010它们并不特权化——真正决定关系识别的是值是否为 wikilink。任何自定义字段如owner: [[person-luca-rossi]]、depends_on: [[xxx]]都会自动进入关系图谱在 RelationshipsPanel.tsx 中统一呈现。系统字段下划线保留命名空间以_开头的字段为系统保留字段承载应用内部行为并默认从标准属性编辑面板隐藏。它们依然是普通 YAML因此可以在 raw 模式下检查或修改。系统字段的嵌套子键同样归系统所有——例如_sheet.cells.B6.num_fmt属于表格编辑器不应作为普通用户属性出现。规范化canonicalization与别名systemMetadata.ts 定义了完整的归一化体系normalizePropertyKey去除首尾空白、转小写、空白转下划线canonicalFrontmatterKey将别名归一到规范键如sidebar label→_sidebar_labelisSystemMetadataKey键以_开头或命中系统别名即判定为系统元数据canonicalFrontmatterWriteKey写入时强制使用规范键CANONICAL_WRITE_KEYS覆盖type及全部系统键。这意味着读取时兼容各种历史写法大小写不敏感、支持sidebar label带空格等写入时则统一落盘为规范键。外观与侧边栏_icon、_color、_sidebar_label、_order_icon类型或笔记的图标。取值三种形态——kebab-case 的 Phosphor 图标名如rocket、folders见 demo 类型文档、emoji如、或 HTTP(S) 图片 URL。ADR 0049 指出图标解析器在类型文档与笔记间共享。_color类型外观颜色如blue、amber。当前主要作用于类型级ADR 0049 提到若未来支持单笔记颜色可复用同一解析模式。_sidebar_label类型在侧边栏显示的标签如 Projects、Areas。_order类型在侧边栏的排序位置。demo 中 demo-vault-v2/type/area.md 即为完整示例--- type: Type icon: folders color: amber sidebar label: Areas ---注意这里使用了带空格的别名sidebar label——读取时会被归一为_sidebar_label。编辑器与列表_width、_display、_pinned_properties、_list_properties_display_width单笔记编辑器宽度覆盖值per-note editor width override。_display显示模式。文本笔记省略该字段表格笔记写sheet与 ADR 0134-sheet-nodes-with-plain-text-workbook-storage.md 的 Sheet 节点方案呼应。_pinned_properties某类型笔记在编辑器内联栏inline bar中固定的属性集合。_list_properties_display某类型笔记在笔记列表中作为芯片或列展示的属性集合。这两个字段将类型的属性呈现策略声明在类型文档 Frontmatter 中由noteListHooks.ts等列表逻辑消费。表格呈现_sheet_sheet承载 Sheet 笔记的呈现元数据网格设置、列宽、行高、单元格格式等。它的嵌套结构整体归系统所有例如_sheet.cells.B6.num_fmt是单元格格式数字格式用户在普通属性面板中不应编辑如需调整应进入 raw 模式。相关序列化契约见 spreadsheet-format.md 与 spreadsheet-functions.md。更多系统元数据除原文档列出的字段外systemMetadata.ts 与 ADR 0008-underscore-system-properties.md 还登记了以下系统键供 raw 模式使用规范键说明写入方_archived归档标记兼容旧键Archived/archived归档操作_trashed回收站标记删除操作_trashed_at删除时间删除操作_favorite收藏标记收藏切换_favorite_index收藏排序收藏重排_organized已整理标记整理流程_sort排序元数据排序操作写入规则一律使用_前缀的规范键读取规则兼容规范键与遗留键大小写不敏感但不做读取时重写。自定义字段与动态关系最灵活的扩展点自定义字段是 Tolaria 最大的扩展空间写任意 YAML 键如tier: 1st见 demo-vault-v2/person-luca-rossi.md只要值包含[[wikilink]]字段即成为关系自动出现在关系面板关系面板、视图过滤view-filters.md、笔记列表列展示_list_properties_display都可以直接使用这些字段无需注册。实战模板一张完整的 Frontmatter综合以上规则一个信息密度较高的笔记 Frontmatter 模板如下--- type: Project status: Active icon: rocket url: https://example.com/docs date: 2026-09-01 belongs_to: [[25q3]] related_to: - [[laputa-qa-reference]] has: - [[task-onboarding]] owner: [[person-luca-rossi]] tier: 1st _width: 90 _display: text _icon: rocket _color: blue _sidebar_label: Projects _order: 1 _pinned_properties: - status - owner _list_properties_display: - status - owner ---要点回顾无_前缀的字段含owner、tier是普通/自定义属性其中含 wikilink 的自动成为关系_前缀字段是系统保留标准属性面板隐藏raw 模式可改写入用规范键读取兼容别名如sidebar label等价于_sidebar_label类型文档与笔记共用同一套 Frontmatter 约定仅以type: Type区分角色。常见问题Q1为什么我在属性面板看不到_favorite、_width这类字段因为以_开头的字段被解析器过滤不进入标准属性编辑 UIADR 0008。这是刻意设计防止内部字段干扰用户编辑。需要修改时切换到 raw 编辑器直接改 YAML 即可。Q2icon和_icon有什么区别两者按同一规范键归一化。_icon是系统字段的规范形态icon是其别名写入时统一落盘为规范键。功能上单笔记的图标会覆盖其类型的图标。Q3我想新增一种关系需要改代码吗不需要。任意字段只要值含[[wikilink]]就会被动态识别为关系ADR 0010Inspector 关系面板自动收录。Q4遗留笔记用了Is A:怎么办读取兼容解析器会回退识别。运行 Repair Vault 可批量迁移为type:ADR 0025。延伸阅读视图过滤表达式view-filters.md自定义视图引擎0040-custom-views-yml-filter-engine.md表格序列化格式spreadsheet-format.md、spreadsheet-functions.md关系机制相关 ADR0010-dynamic-wikilink-relationship-detection.md、0035-path-suffix-wikilink-resolution.md系统属性约定0008-underscore-system-properties.md图标解析实现noteIcon.ts对应resolveNoteIcon路径以仓库实际为准规范化实现systemMetadata.ts【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考