刚接触YAML的时，为了美观、直观，YAML的属性名使用了中文，后期发现需要程序化处理文档、dataview时，颇有不便。所以：

在代码层面，要坚持只使用英文作为属性名，且遵循事实标准；
在笔记正文中，通过 YAML Frontmatter 的“别名”功能，让表头显示为中文。

YAML Frontmatter使用详解

YAML Frontmatter 是 Obsidian 中管理笔记元数据的核心功能，它位于 Markdown 文件顶部，使用 --- 包裹，以键值对形式存储信息，为笔记的组织、检索和自动化提供了结构化基础。

📝 一、基本语法与结构

1.1 基本格式

Frontmatter 必须位于文件的最开头，格式如下：

---
key1: value1
key2: value2
tags:
  - tag1
  - tag2
---

# 正文标题

关键规则：

以 --- 开始，以 --- 结束
结束的 --- 后必须跟一个空行，再开始正文
键名与值之间用英文冒号和空格分隔：key: value
属性名在同一个文件内必须唯一

1.2 多值表示

一个键对应多个值时，有两种写法：

# 行内数组写法
tags: [pkm, obsidian, yaml]

# 列表写法（推荐，更清晰）
tags:
  - pkm
  - obsidian
  - yaml

1.3 JSON 替代格式

Obsidian 也支持 JSON 格式的 Frontmatter（保存后会自动转为 YAML）：

---{
  "tags": ["journal", "daily"],
  "publish": false
}---

🎯 二、Obsidian 原生支持的属性

Obsidian 原生识别三个特殊属性：

属性名	类型	作用
`tags`	标签列表	为笔记添加标签，与行内 `#tag` 功能等价
`aliases`	文本列表	为笔记设置别名，用于链接建议和搜索
`cssclasses`	文本列表	为笔记应用自定义 CSS 类（需配合 CSS 片段）

示例：

---
tags:
  - projects/active
  - review/weekly
aliases:
  - 替代标题
  - 简写名称
cssclasses:
  - wide-page
  - no-title
---

⚠️ 注意：旧版使用的 tag、alias、cssclass（单数形式）已在 Obsidian 1.4+ 中弃用，建议改用复数形式。

🔢 三、属性类型系统

Obsidian 支持 6 种属性类型，且一旦某个属性名在全库中被赋予了类型，该名称在所有文件中都会使用同一类型：

类型	说明	示例
文本	单行字符串，URL 和内部链接需加引号	`title: My Note`
列表	多个值，每行以 `-` 开头	`cast: - A - B`
数字	整数或小数	`year: 1977`
复选框	`true`/`false`，在 Live Preview 中显示为可交互复选框	`favorite: true`
日期	ISO 格式 YYYY-MM-DD，会显示日期选择器	`date: 2024-01-20`
日期与时间	ISO 格式含时间	`time: 2024-01-20T10:30:00`
标签	仅用于 `tags` 属性的特殊类型	见上文 tags 示例

🛠️ 四、Obsidian Publish 专用属性

如果你使用 Obsidian Publish，以下属性控制发布行为：

属性名	类型	作用
`publish`	复选框	`true` 发布，`false` 不发布
`permalink`	文本	自定义发布页面的 URL 路径
`description`	文本	SEO 元描述和社交媒体预览
`image` / `cover`	文本	社交媒体预览图片路径

示例：

---
publish: true
permalink: my-custom-url
description: 这篇文章介绍了 Obsidian 的 YAML Frontmatter 用法
image: "Attachments/cover.png"
---

🔌 五、与其他插件的联动

5.1 Dataview

Dataview 是使用 Frontmatter 最强大的插件，可以将元数据查询并展示为表格：

TABLE date, author, status
FROM "Projects"
WHERE status = "active"
SORT date DESC

5.2 Templater

在模板中自动填充元数据：

---
title: <% tp.file.title %>
date: <% tp.date.now("YYYY-MM-DD") %>
tags: []
author: 
---

5.3 Linter

Linter 可以自动格式化、排序、补充 Frontmatter 字段，例如自动添加 created 和 updated 时间戳。

📋 六、最佳实践

6.1 命名规范

使用小写字母，单词间用下划线 _ 或直接连写
全库保持属性名一致：created 比 date 更明确；不要混用 created 和 create_date
不要使用重复或含义重叠的属性

6.2 标签格式

⚠️ 不要在 YAML 标签前加 #：tags: - pkm ✅，tags: - #pkm ❌
使用列表格式：- tag1 优于 [tag1, tag2]

6.3 日期格式

统一使用 ISO 格式 YYYY-MM-DD
需要时间时使用 YYYY-MM-DDThh:mm:ss

6.4 内部链接格式

含有内部链接 [[Link]] 的值必须加引号，否则会被解析为 YAML 语法错误
```
# ✅ 正确
related: "[[Another Note]]"

# ❌ 错误
related: [[Another Note]]
```

6.5 特殊字符处理

值若包含 : # " [ ] { } 等特殊字符，建议用引号包裹：

title: "AI Era: Thriving Framework"  # 冒号需引号
quote: 'He said, "Hello."'

⚠️ 七、常见陷阱与限制

7.1 嵌套属性限制

Obsidian 的属性视图（Property View）不支持嵌套对象的编辑。如果需要使用嵌套结构（如 author.name），必须在源码模式下编辑，且 Dataview 查询也可能需要特殊处理。

如果确实需要嵌套数据，建议改用列表结构：

# 避免
author:
  name: John
  email: john@example.com

# 推荐
author_name: John
author_email: john@example.com

7.2 属性类型锁定

一旦某个属性名（如 status）在某篇笔记中被赋予了类型（如复选框），该名称在所有笔记中都会被锁定为该类型，无法更改。使用 Properties view 插件可以查看和管理全库的属性类型。

7.3 位置要求

Frontmatter 必须严格位于文件最顶部，任何字符（包括空格、BOM 头）出现在 --- 之前都会导致解析失败。

💡 八、总结

YAML Frontmatter 是 Obsidian 知识管理的核心基础设施，它让笔记从"纯文本"升级为"结构化数据"。合理使用 Frontmatter，可以：

🔍 通过 Dataview 实现类数据库查询
🏷️ 系统化组织标签和别名
🤖 配合 Linter 实现自动化元数据管理
📤 控制 Publish 发布行为

建议从核心属性（tags、date、status）开始，逐步扩展，并利用 Linter 保持格式统一。

常见问题及处理方案

在 Dataview 中处理中英文混合的字段名，核心思路是：在代码中统一使用英文（或拼音）字段名，再通过行内字段的别名功能同步映射中文名。这样既能保证 Dataview 查询不出错，也能在阅读笔记时保留中文的直观性。

💡 解决方案：统一字段名 + 别名映射

这个方法的核心是：在代码层面，坚持只使用英文作为属性名，但在笔记正文中，通过 YAML Frontmatter 的“别名”功能，让你在阅读时能看到中文名称。

具体操作步骤：

定义笔记属性：在笔记开头的 YAML Frontmatter 中，只定义一个英文（或拼音）字段，比如 status。
添加字段别名（Alias）：同样在 YAML 中，使用 aliases 字段为这个属性添加一个中文别名，例如“状态”。
在 Dataview 中查询：编写 Dataview 查询时，始终使用其定义的英文名 status。

代码示例：

你的 Dataview 查询代码：

TABLE status AS "状态"
FROM "你的笔记文件夹"
WHERE status

通过 AS "状态"，你在最终生成的表格中看到的表头就会是“状态”，而不是“status”。

⚠️ 避坑指南：为什么不用中文字段？

直接在笔记中混用中英文属性名（例如有的用 status，有的用“状态”），会导致 Dataview 处理时出现问题：

无法自动合并：Dataview 视 status 和“状态”为两个完全不同的字段，无法在一个表格列中同时显示它们的数据。
查询语法限制：使用中文字段名时，查询语法要求十分严格，特殊符号和空格容易引发报错。而英文字段名配合 row[...] 语法会更稳定。
增加复杂度：在 WHERE、SORT 等查询语句中，纯英文的字段名写起来更简单，可读性也更高。

📝 实际操作流程

统一迁移：逐步将所有笔记的中文属性名（如“标签”、“时间”）统一为英文（如 tag、date）。
优化查询：在你的 Dataview 查询语句中，使用 AS "中文名" 的方式，将英文表头显示为你期望的中文。
善用别名：如果必须保留中文阅读习惯，就使用上面提到的 aliases 方式进行映射。这能在不破坏数据规范的前提下，兼顾阅读体验。

遵循这个“代码用英文，显示用中文”的原则，就能解决字段混用的问题，让 Dataview 准确、统一地管理和展示你的数据。

YAML Front Matter 事实标准

YAML Front Matter 没有官方的强制标准，不同平台和工具的字段会有差异。不过，经过长期发展，一套“事实标准”的元数据键名已经被广泛接受。

📄 核心信息：文档的“身份证”。title (标题)、description (摘要)、author/authors (作者)、date (创建日期)、updated (更新日期)。

🏷️ 分类标签：内容的“归档夹”。tags (标签列表)、categories (分类层次)。

🔧 技术控制：决定页面“如何显示”。layout (页面模板)、permalink (永久链接)、draft (草稿状态)、slug (URL友好名称)。

🔗 扩展与导航：关联其他资源。image/thumbnail (封面图)、aliases (别名)、redirect_from (重定向)。

🌐 多语言与SEO：针对搜索引擎优化。lang (语言)、keywords (关键词)、excerpt (纯文本摘要)。

`aliases` 和 `categories` 辨析

aliases 和 categories 在 Obsidian 中扮演着截然不同的角色。简单来说：aliases 是笔记的“替身”，解决的是“同一个东西，不同叫法”的问题；而 categories 是笔记的“归类”，解决的是“这个东西属于哪一类”的问题。

它们的核心区别如下：

特性	aliases (别名)	categories (类目)
🎯 核心目的	链接与引用：让你能用不同的名字链接到同一篇笔记。	组织与分类：将笔记归类，构建知识体系。
🏷️ 本质	笔记的替代名称或代名词。	一种元数据属性，用于描述笔记的从属关系。
🔗 如何工作	在 YAML 中列出备选名称，输入 `[[别名]]` 即可链接到原笔记。	通常配合 `categories: [[类目名]]` 使用，指向一个代表该“类目”的独立笔记。
🔍 主要用途	使用缩写 (e.g., `AI` 指代 `人工智能`) 使用昵称 (e.g., `老李` 指代 `李经理`) 使用不同语言的名称	构建知识树的主干 (e.g., `[[项目管理]]`, `[[编程语言]]`) 通过反向链接聚合所有同类笔记配合 Dataview 建立知识地图 (MOC)
📝 YAML 示例	`yaml<br>---<br>aliases:<br> - AI<br> - 人工智能<br>---<br>`	`yaml<br>---<br>categories:<br> - [[技术]]<br> - [[Obsidian教程]]<br>---<br>`
🔗 链接方式	`[[人工智能	AI]]`(输入`[[AI]]` 后自动补全)
🎨 可视化表现	在反向链接面板的“非关联提及”中，笔记别名会被识别。	在知识图谱中，不同笔记会清晰地指向同一个“类目”中心节点。

🧐 深入解读：它们各自的独特优势

别名的核心价值：消除歧义，简化引用

Aliases 的核心价值在于降低笔记之间的链接成本，让你不必在每次引用时都输入完整的笔记标题。

提升写作流畅度：假设你有一篇笔记叫《论 Obsidian 中 YAML Frontmatter 的高级应用与最佳实践》，每次要链接它都输入全称非常痛苦。设置一个 aliases: [YAML教程] 后，你只需输入 [[YAML教程]] 即可。这让你能更专注于内容创作，而不是被链接操作打断。
发现隐性关联：如果你在另一篇笔记中直接写了“YAML教程”这几个字（而没有创建链接），它也会出现在原笔记的反向链接“非关联提及”列表中。你可以一键将其转换为正式链接，这能帮你发现很多自己都未曾想到的知识关联。

类目的核心价值：构建体系，表达关系

Categories 是一种更为结构化的组织方式，它超越了简单的“命名”，强调的是笔记与笔记之间的语义关系。

表达精准的关系：这是 Categories 相对于标签（Tags）最大的优势。你可以明确地定义笔记和类目之间的关系类型。
- 你可以用 categories: [[电影]] 表示笔记《肖申克的救赎》是一部电影。
- 你可以用 topic: [[电影]] 表示一篇《蒙太奇手法研究》的主题是电影。
- 你还可以用 hobby: [[电影]] 表示朋友小张的兴趣是电影。
  而在同一篇笔记中，你无法用 #电影 这一个标签来表达上述三种不同的关系。Categories 通过不同的属性名 (categories, topic, hobby) 实现了这种精确性。
易于维护和扩展：当某个类目需要改名或调整时（比如，当“重庆”从“四川”独立出来后），Categories 的优势就体现出来了。使用 categories 时，你只需修改“重庆”这一篇笔记的 province 属性（从 [[四川]] 改为 [[直辖市]]）即可。而如果是用 #四川/重庆 这样的标签，你需要找到所有包含此标签的笔记并逐一修改，维护成本高得多。

🤔 那么，我该用哪个？

这取决于你的需求。两者并非互斥，反而可以协同工作，构建一个强大而灵活的知识管理系统。

选择 aliases，当你的目的是：

让你自己或他人更方便地链接到这篇笔记。
处理那些有多个名称的实体（如人物、术语、项目）。
在写作时减少输入负担，保持思维流畅。

选择 categories，当你的目的是：

从宏观上构建和梳理你的知识库结构。
需要精准表达一篇笔记与其他笔记（尤其是作为“类目”的笔记）的关系。
建立一个稳定、易于维护的层级化知识网络。

一个很好的实践是：用 Categories 搭建你知识库的骨架，形成一个个清晰的知识领域（如 [[个人成长]], [[软件开发]]）；用 Tags 来标注笔记的状态、类型等属性（如 #todo, #favorite）；而 Aliases 则作为你写作时的“快捷键”，让你能丝滑地在这副骨架上穿针引线。