252 lines
12 KiB
Markdown
252 lines
12 KiB
Markdown
---
|
||
tags:
|
||
- yaml
|
||
aliases:
|
||
- yaml用法
|
||
笔记类型:
|
||
日期: 2026/4/17
|
||
---
|
||
**YAML (YAML Ain't Markup Language) 是一种以数据为中心、对人类友好的数据序列化语言。它因其简洁和高可读性而备受青睐，尤其是在配置文件和知识管理领域。**
|
||
|
||
### 1. YAML的应用场景
|
||
#### 作为Markdown知识笔记的元数据
|
||
##### 什么是YAML Front Matter？
|
||
|
||
- **定义:** 它是添加到文件第一行的一系列纯文本属性，用于在Markdown等文件中添加元数据。
|
||
- **别称:** 也常被称为 front matter、页眉、前页、扉页、前言。
|
||
- **作用:** 它是一种人类可读、文件级的元数据，为笔记本身添加了结构化的信息，使得软件可以基于这些信息进行强大的自动化处理，例如分类、查询和筛选。
|
||
|
||
|
||
在Obsidian、Joplin等众多工具中，YAML Front Matter是核心功能。它为一篇笔记提供了超越其正文内容的“身份信息”。
|
||
|
||
**示例：** 在一篇Obsidian笔记的开头，你可以这样定义元数据。
|
||
|
||
```yaml
|
||
---
|
||
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的基础语法
|
||
#### <mark style="background: #FFF3A3A6;">核心规则</mark>
|
||
|
||
1. **格式**：采用“关键词: 值”的键值对形式（关键词 英文冒号 空格 值）。
|
||
样例：
|
||
```yaml
|
||
views:
|
||
- type: table
|
||
name: 表格
|
||
order:
|
||
- file.name
|
||
- file.fullname
|
||
- file.tags
|
||
- file.folder
|
||
```
|
||
2. **空格与缩进**：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 或 ~ 表示。
|
||
|
||
**示例代码：**
|
||
```yaml
|
||
# 字符串
|
||
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)
|
||
|
||
序列是一组有序的值，类似于编程语言中的数组或列表。每个列表项由一个短横线 (-) 和一个空格开头。
|
||
|
||
**示例代码：**
|
||
```yaml
|
||
# 一个简单的水果列表
|
||
fruits:
|
||
- Apple
|
||
- Orange
|
||
- Strawberry
|
||
|
||
# 也可以使用行内（inline）格式
|
||
fruits_inline: [Apple, Orange, Strawberry]
|
||
```
|
||
|
||
##### 3. 映射 (Mappings / Dictionaries)
|
||
|
||
映射是键值对（key-value）的集合，类似于编程语言中的字典或哈希表。
|
||
|
||
**示例代码：**
|
||
```yaml
|
||
# 描述一个用户的基本信息
|
||
user:
|
||
name: John Doe
|
||
age: 30
|
||
email: john.doe@example.com
|
||
|
||
# 也可以使用行内（inline）格式
|
||
user_inline: {name: Jane Doe, age: 28}
|
||
```
|
||
|
||
#### 复合结构：数据嵌套
|
||
|
||
以上三种基本结构可以自由组合，形成复杂的数据结构。这是 YAML 强大功能的核心体现。
|
||
|
||
**示例代码：**
|
||
```yaml
|
||
# 一个用户列表，每个用户都是一个包含详细信息的映射
|
||
users:
|
||
# 第一个用户
|
||
- name: Alice
|
||
age: 28
|
||
is_admin: true
|
||
roles: # "roles" 的值是一个序列
|
||
- editor
|
||
- publisher
|
||
# 第二个用户
|
||
- name: Bob
|
||
age: 35
|
||
is_admin: false
|
||
roles:
|
||
- viewer
|
||
```
|
||
|
||
#### 多行文本
|
||
**字面量块 `|`**：保留每一个换行。适合要“按原样呈现”的文本。
|
||
```yaml
|
||
about: |
|
||
第一行
|
||
第二行
|
||
第三行
|
||
```
|
||
解析后：`"第一行\n第二行\n第三行\n"`（注意末尾有 1 个换行，因为默认是clip-保留一个结尾换行（\n），但丢掉多余的尾随空行）。
|
||
|
||
**折叠块** `>`：把换行折叠为空格（空行保留为换行）
|
||
```yaml
|
||
about: >
|
||
这一段
|
||
被写成了多行
|
||
但会折叠成一行显示
|
||
|
||
空行用来分段
|
||
分段之间会出现真正的换行
|
||
```
|
||
解析后：`"这一段 被写成了多行 但会折叠成一行显示\n\n空行用来分段 分段之间会出现真正的换行\n"`
|
||
（你看到：单个换行被折成空格；空行保留为 `\n`；末尾仍有一个换行，因为clip-保留一个结尾换行（\n），但丢掉多余的尾随空行）
|
||
|
||
#### 注释
|
||
|
||
使用井号 (#) 进行单行注释。从 # 开始到该行末尾的所有内容都会被忽略。
|
||
```yaml
|
||
# 这是一个注释，它将被解析器忽略。
|
||
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](https://yamlchecker.com/) | 快速验证YAML语法是否正确，进行格式化和美化，适合临时检查。 |
|
||
| **Prettier** | 代码格式化工具，例如[Prettier · Opinionated Code Formatter · Prettier](https://prettier.io/) | 通过插件支持YAML，可以在项目中统一代码风格，实现保存时自动格式化。 | |