YAML 新手入门教程：从Obsidian元数据，到OpenAI GPT5官方提示词，解锁你的必备技能

Aug 22, 2025 下载文件

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: [email protected]

# 也可以使用行内（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，可以在项目中统一代码风格，实现保存时自动格式化。