12 KiB
tags, aliases, type, status, star, date
| tags | aliases | type | status | star | date |
|---|---|---|---|---|---|
| false |
YAML (YAML Ain't Markup Language) 是一种以数据为中心、对人类友好的数据序列化语言。它因其简洁和高可读性而备受青睐，尤其是在配置文件和知识管理领域。
1. YAML的应用场景
作为Markdown知识笔记的元数据
什么是YAML Front Matter？
- 定义: 它是添加到文件第一行的一系列纯文本属性，用于在Markdown等文件中添加元数据。
- 别称: 也常被称为 front matter、页眉、前页、扉页、前言。
- 作用: 它是一种人类可读、文件级的元数据，为笔记本身添加了结构化的信息，使得软件可以基于这些信息进行强大的自动化处理，例如分类、查询和筛选。
在Obsidian、Joplin等众多工具中，YAML Front Matter是核心功能。它为一篇笔记提供了超越其正文内容的“身份信息”。
示例： 在一篇Obsidian笔记的开头，你可以这样定义元数据。
---
title: "我的Obsidian使用技巧"
date: 2025-08-21
tags: [Obsidian, 知识管理, YAML]
aliases: [Obsidian技巧, 如何使用Obsidian]
---
作为AI提示词的格式
当构建复杂的AI提示词（Prompt）时，需要一种能够清晰组织指令、变量和上下文的格式。YAML在这方面表现出色。
| 格式 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|
| YAML | 结构清晰，可读性高，易于手写和维护，适合表达复杂的层级关系。 | 语法依赖严格的缩进，对新手不友好。 | 复杂的、多参数的、需要模板化的AI任务。 |
| Markdown | 自由流畅，接近自然语言，适合编写故事或对话型提示词。 | 结构性差，难以定义精确的配置参数。 | 文学创作、角色扮演、简单的问答。 |
| JSON | 机器解析极为友好，语法严格，不易产生歧义，是API交互的标准。 | 手写繁琐，括号和引号过多，可读性较差。 | 程序化的API调用，自动化工作流。 |
作为配置文件
YAML是许多现代软件和工具首选的配置文件格式，因为它能清晰地表达复杂的配置结构。
-
智能家居自动化: 在流行的开源智能家居平台 Home Assistant 中，用户主要通过编辑YAML文件（如 configuration.yaml）来设置自动化场景。例如，“当太阳下山时，自动打开客厅的灯”或者“当传感器检测到湿度低于40%时，开启加湿器”这样的规则，都是通过YAML来定义的。
-
PC游戏的插件与Mod: 许多PC游戏（尤其是沙盒类游戏如《我的世界》Minecraft）的服务器插件或Mod，都使用YAML文件作为配置文件。服务器的管理员或玩家可以通过修改这些 .yml 文件，来调整游戏规则、设置商店物品价格、或者自定义玩家加入时的欢迎信息，而无需编写任何代码。
2. YAML的基础语法
核心规则
- 格式：采用“关键词: 值”的键值对形式（关键词 英文冒号 空格 值）。 样例：
views:
- type: table
name: 表格
order:
- file.name
- file.fullname
- file.tags
- file.folder
- 空格与缩进：YAML 的语法对缩进和空格极其敏感，这是其结构的核心。理解并遵守这些规则是正确编写 YAML 的关键。
- 使用空格进行缩进：通过空格缩进来表示数据的层级关系和嵌套。
- 严禁使用 Tab 键：只能使用空格进行缩进，绝不能使用 Tab 键。混合使用或单独使用 Tab 键都会导致解析错误。
- 缩进需保持一致：同一层级的元素必须左侧对齐（即保持相同的缩进量）。通常推荐使用 2 个或 4 个空格作为一级缩进。
- 冒号和短横线后的空格：
- 键值对的冒号 (:) 后面必须跟一个空格。
- 列表项的短横线 (-) 后面必须跟一个空格。
基本数据结构
YAML 主要由三种基本数据结构组成：纯量（Scalars）、序列（Sequences/Lists）和映射（Mappings/Dictionaries）。
1. 纯量 (Scalars)
纯量是单个的、不可分割的值，是 YAML 中最基本的数据单元。
- 字符串 (String)
- 默认无需引号：my_string: Hello YAML
- 单引号 (')：不会转义特殊字符，所有内容视为字面量。
- 双引号 (")：会转义特殊字符，例如 \n 会被解析为换行符。
- 数字 (Number)：包括整数和浮点数。
- 布尔值 (Boolean)：true 或 false。
- 空值 (Null)：使用 null 或 ~ 表示。
示例代码：
# 字符串
string_value: Hello YAML
quoted_string: "This is a string with a \n newline."
# 数字
integer_value: 1024
float_value: 3.14159
# 布尔值
is_active: true
is_enabled: false
# 空值
empty_value: null
another_empty: ~
2. 序列 (Sequences / Lists)
序列是一组有序的值，类似于编程语言中的数组或列表。每个列表项由一个短横线 (-) 和一个空格开头。
示例代码：
# 一个简单的水果列表
fruits:
- Apple
- Orange
- Strawberry
# 也可以使用行内（inline）格式
fruits_inline: [Apple, Orange, Strawberry]
3. 映射 (Mappings / Dictionaries)
映射是键值对（key-value）的集合，类似于编程语言中的字典或哈希表。
示例代码：
# 描述一个用户的基本信息
user:
name: John Doe
age: 30
email: john.doe@example.com
# 也可以使用行内（inline）格式
user_inline: {name: Jane Doe, age: 28}
复合结构：数据嵌套
以上三种基本结构可以自由组合，形成复杂的数据结构。这是 YAML 强大功能的核心体现。
示例代码：
# 一个用户列表，每个用户都是一个包含详细信息的映射
users:
# 第一个用户
- name: Alice
age: 28
is_admin: true
roles: # "roles" 的值是一个序列
- editor
- publisher
# 第二个用户
- name: Bob
age: 35
is_admin: false
roles:
- viewer
多行文本
字面量块 |：保留每一个换行。适合要“按原样呈现”的文本。
about: |
第一行
第二行
第三行
解析后："第一行\n第二行\n第三行\n"（注意末尾有 1 个换行，因为默认是clip-保留一个结尾换行（\n），但丢掉多余的尾随空行）。
折叠块 >：把换行折叠为空格（空行保留为换行）
about: >
这一段
被写成了多行
但会折叠成一行显示
空行用来分段
分段之间会出现真正的换行
解析后："这一段 被写成了多行 但会折叠成一行显示\n\n空行用来分段 分段之间会出现真正的换行\n"
（你看到：单个换行被折成空格；空行保留为 \n；末尾仍有一个换行，因为clip-保留一个结尾换行（\n），但丢掉多余的尾随空行）
注释
使用井号 (#) 进行单行注释。从 # 开始到该行末尾的所有内容都会被忽略。
# 这是一个注释，它将被解析器忽略。
key: value # 这也是一个行内注释。
3. YAML在Obsidian中的实践
在Obsidian中，YAML元数据是实现知识库从简单笔记集合升级为强大个人数据库的关键。它为每篇笔记赋予了结构化的“属性”，使得自动化管理和知识发现成为可能。
从YAML Front Matter到“属性”视图
最初，YAML元数据需要手动在笔记顶端的---分隔符之间编写。为了降低使用门槛并提升体验，Obsidian推出了核心的“属性”（Properties）功能。
- 可视化界面：你不再需要手动输入YAML代码，可以通过一个直观的界面在笔记顶部添加、编辑或删除属性。这个界面提供了文本、数字、日期、复选框和列表等多种属性类型，并会自动补全已存在的属性名和值，极大地保证了数据的一致性。
- 源码对应：你在属性界面上的所有操作，都会实时、准确地转换成笔记源文件顶部的标准YAML Front Matter。你随时可以切换到“源码模式”查看和编辑底层的YAML代码。
Obsidian原生支持的特殊属性
Obsidian会对一些特定的YAML属性赋予特殊功能，让它们与软件的核心功能深度集成。
| 属性 (Property) | 功能描述 (Description) | 格式要求 (Format Requirement) |
|---|---|---|
tags |
定义笔记的标签，会自动被Obsidian的“标签面板”识别和索引。 | 必须是列表（Array）格式。 |
aliases |
为笔记设置一个或多个“别名”，方便通过别名进行链接和搜索。 | 必须是列表（Array）格式。 |
cssclasses |
为当前笔记应用一个或多个自定义的CSS样式片段，实现特定的视觉效果。 | 必须是列表（Array）格式。 |
重要更新：从Obsidian 1.4版本开始，官方统一并强制要求这些原生属性必须使用复数形式（
tags,aliases,cssclasses），并且它们的值必须是列表格式。
设计你的个人化元数据系统
YAML的真正威力在于自定义。通过建立一套规范的元数据体系，你可以为自己的知识库量身打造强大的分类和检索系统。
| 实践建议 (Practice) | 目的与描述 (Purpose & Description) | 示例 (Example) |
|---|---|---|
| 规范命名 | 为了便于Dataview等插件查询，建议属性名全部使用小写，并用下划线代替空格。 | creation_date |
| 笔记分类 | 使用type或category属性来定义笔记的类型，这是进行分类查询的基础。 |
type: book |
| 状态追踪 | 使用status属性来管理笔记的生命周期或项目的进度。 |
status: seedling (想法) |
| 建立关联 | 除了使用[[链接]]，你还可以用属性来定义更明确的关系。 |
author: [[作者A]] |
通过Obsidian插件，让你的元数据“活”起来
你精心维护的YAML属性，通过插件可以实现知识的自动化组织与呈现。
| 插件 (Plugin) | 核心功能 (Core Function) | 应用实例 (Application Example) |
|---|---|---|
| Dataview | 使用简单的查询语言（DQL）从整个知识库中筛选、排序和展示笔记，自动生成动态的笔记列表和表格。 | 创建一个“动态首页”，自动汇总所有 status: in-progress 的任务。 |
| Bases | (官方插件) 提供一个可视化的、类似Notion数据库的界面（表格、看板等）来浏览和批量编辑笔记的元数据。 | 以看板视图来管理所有 type: project 的笔记，并拖动卡片来改变它们的 status 属性。 |
| Metadata Menu | 极大地增强了属性的编辑体验，可以为属性预设可选值或创建依赖关系，实现更高效、规范的元数据录入。 | 为status属性设置固定的下拉菜单选项："待办"、"进行中"、"完成"。 |
4. YAML的编辑器或格式化工具
| 工具 | 类型 | 主要功能 |
|---|---|---|
| VS Code + YAML 插件 | 桌面编辑器 | 语法高亮、自动补全、实时错误校验、代码折叠、格式化。 |
| Online YAML Parsers | 在线工具，例如YAML Checker - The YAML Syntax Validator | 快速验证YAML语法是否正确，进行格式化和美化，适合临时检查。 |
| Prettier | 代码格式化工具，例如Prettier · Opinionated Code Formatter · Prettier | 通过插件支持YAML，可以在项目中统一代码风格，实现保存时自动格式化。 |