企业官网建设流程全解析

Tolaria Frontmatter 字段全解析：从 type/status 到系统下划线属性的完整指南

【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria

Frontmatter 是 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：实体类型的规范字段

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()判断）、image（HTTP(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、has

Tolaria 支持任意关系语义，内置三个约定字段：

• 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_label）；
• isSystemMetadataKey：键以_开头或命中系统别名即判定为系统元数据；
• 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 模式使用）：

写入规则：一律使用_前缀的规范键；读取规则：兼容规范键与遗留键（大小写不敏感），但不做读取时重写。

自定义字段与动态关系：最灵活的扩展点

自定义字段是 Tolaria 最大的扩展空间：

1. 写任意 YAML 键，如tier: 1st（见 demo-vault-v2/person-luca-rossi.md）；
2. 只要值包含[[wikilink]]，字段即成为关系，自动出现在关系面板；
3. 关系面板、视图过滤（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这类字段？因为以_开头的字段被解析器过滤，不进入标准属性编辑 UI（ADR 0008）。这是刻意设计，防止内部字段干扰用户编辑。需要修改时切换到 raw 编辑器直接改 YAML 即可。

Q2：icon和_icon有什么区别？两者按同一规范键归一化。_icon是系统字段的规范形态，icon是其别名；写入时统一落盘为规范键。功能上，单笔记的图标会覆盖其类型的图标。

Q3：我想新增一种关系，需要改代码吗？不需要。任意字段只要值含[[wikilink]]就会被动态识别为关系（ADR 0010），Inspector 关系面板自动收录。

Q4：遗留笔记用了Is A:怎么办？读取兼容：解析器会回退识别。运行 Repair Vault 可批量迁移为type:（ADR 0025）。

延伸阅读

• 视图过滤表达式：view-filters.md
• 自定义视图引擎：0040-custom-views-yml-filter-engine.md
• 表格序列化格式：spreadsheet-format.md、spreadsheet-functions.md
• 关系机制相关 ADR：0010-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