332 lines
6.8 KiB
Markdown
332 lines
6.8 KiB
Markdown
---
|
||
title: 如何使用 frontmatter
|
||
createTime: 2024/09/18 09:19:36
|
||
permalink: /article/ecxnxxd0/
|
||
---
|
||
|
||
::: info 说明
|
||
本文 翻译 [Introduction to YAML](https://dev.to/paulasantamaria/introduction-to-yaml-125f) 的部分内容。
|
||
用于简单说明如何在 markdown 文件中使用 frontmatter。
|
||
|
||
如果您具有良好的英语阅读基础，为避免翻译可能存在的内容失真，建议您阅读原文。
|
||
|
||
原文地址： <https://dev.to/paulasantamaria/introduction-to-yaml-125f> 。
|
||
:::
|
||
|
||
## 介绍
|
||
|
||
YAML 是一种数据序列化语言，通常用于配置文件，例如
|
||
[Open API 规范](https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v2.0/yaml/api-with-examples.yaml) 或 [CI/CD 管道](https://docs.gitlab.com/ee/ci/yaml/)。
|
||
|
||
::: note 有趣的事实！🤓
|
||
根据 [YAML 1.0 规范文档 （2001-05-26）](https://yaml.org/spec/history/2001-05-26.html) 首字母缩略词
|
||
“YAML” 代表 “Yet Another Markup Language”，
|
||
但后来在 [2002-04-07 规范](https://yaml.org/spec/history/2002-04-07.html) 中更改为递归首字母缩略词“YAML Ain't Markup Language”。
|
||
:::
|
||
|
||
正如最新规范中所述，__YAML__ 旨在 __对处理数据的人友好__，并通过 __最大限度地减少结构字符的使用来实现“独特的干净度”__，
|
||
允许数据以自然和有意义的方式显示。
|
||
|
||
最新规范还指出，YAML _1.2 作为官方子集符合 JSON_ ，这意味着大多数 JSON 文档都可以解析为 YAML。
|
||
|
||
YAML 通过使用基于缩进的范围界定（类似于 Python）轻松检查数据结构。
|
||
|
||
::: note 另一个有趣的事实！🤓
|
||
DEV.to 文章使用 YAML 来定义自定义变量，如标题、描述、标签等。
|
||
:::
|
||
|
||
## 基本语法
|
||
|
||
YAML 文档基本上是 __键值对的集合__，其中值可以像字符串一样简单，也可以像树一样复杂。
|
||
|
||
以下是有关 YAML 语法的一些说明：
|
||
|
||
- __缩进用于表示结构__。不允许使用制表符，只要子节点的缩进量比父节点大，空格的数量就无关紧要。
|
||
- 允许使用 UTF-8、UTF-16 和 UTF-32 编码。
|
||
|
||
### 字符串
|
||
|
||
```md
|
||
---
|
||
# 字符串不需要引号：
|
||
title: Introduction to YAML
|
||
|
||
# 但你仍可使用它们：
|
||
title-w-quotes: 'Introduction to YAML'
|
||
|
||
# 多行字符串以 | 开头
|
||
execute: |
|
||
npm ci
|
||
npm build
|
||
npm test
|
||
---
|
||
```
|
||
|
||
上面的代码将转换为 JSON 为：
|
||
|
||
```json
|
||
{
|
||
"title": "Introduction to YAML",
|
||
"title-w-quotes": "Introduction to YAML",
|
||
"execute": "npm ci\nnpm build\nnpm test\n"
|
||
}
|
||
```
|
||
|
||
### 数字
|
||
|
||
```md
|
||
---
|
||
# 整数：
|
||
age: 29
|
||
|
||
# 浮点数：
|
||
price: 15.99
|
||
|
||
# 科学计数法：
|
||
population: 2.89e+6
|
||
---
|
||
```
|
||
|
||
上面的代码将转换为 JSON 为：
|
||
|
||
```json
|
||
{
|
||
"age": 29,
|
||
"price": 15.99,
|
||
"population": 2890000
|
||
}
|
||
```
|
||
|
||
### 布尔值
|
||
|
||
```md
|
||
---
|
||
# 布尔值可以有不同的表示方式：
|
||
published: false
|
||
published: False
|
||
published: FALSE
|
||
---
|
||
```
|
||
|
||
以上所有内容都将转换为 JSON，如下所示：
|
||
|
||
```json
|
||
{
|
||
"published": false
|
||
}
|
||
```
|
||
|
||
### Null 值
|
||
|
||
```md
|
||
---
|
||
# Null 值可以通过不设置值来表示：
|
||
null-value:
|
||
|
||
# 或者更明确地说：
|
||
null-value: null
|
||
null-value: NULL
|
||
null-value: Null
|
||
---
|
||
```
|
||
|
||
以上所有内容都将转换为 JSON，如下所示：
|
||
|
||
```json
|
||
{
|
||
"null-value": null
|
||
}
|
||
```
|
||
|
||
### 日期和时间戳
|
||
|
||
可以使用 ISO 格式的日期，如下所示：
|
||
|
||
```md
|
||
---
|
||
date: 2002-12-14
|
||
canonical: 2001-12-15T02:59:43.1Z
|
||
iso8601: 2001-12-14t21:59:43.10-05:00
|
||
spaced: 2001-12-14 21:59:43.10 -5
|
||
---
|
||
```
|
||
|
||
### Sequences 序列
|
||
|
||
序列允许我们在 YAML 中定义列表：
|
||
|
||
```md
|
||
---
|
||
# 使用连字符的数字列表：
|
||
numbers:
|
||
- one
|
||
- two
|
||
- three
|
||
|
||
# 内联版本：
|
||
numbers: [ one, two, three ]
|
||
---
|
||
```
|
||
|
||
上述两个序列都将解析为 JSON，如下所示：
|
||
|
||
```json
|
||
{
|
||
"numbers": [
|
||
"one",
|
||
"two",
|
||
"three"
|
||
]
|
||
}
|
||
```
|
||
|
||
### 嵌套值
|
||
|
||
我们可以使用上述所有类型来创建具有嵌套值的对象，如下所示：
|
||
|
||
```md
|
||
---
|
||
# 一九八四小说数据。
|
||
nineteen-eighty-four:
|
||
author: George Orwell
|
||
published-at: 1949-06-08
|
||
page-count: 328
|
||
description: |
|
||
A Novel, often published as 1984, is a dystopian novel by English novelist George Orwell.
|
||
It was published in June 1949 by Secker & Warburg as Orwell's ninth and final book.
|
||
---
|
||
```
|
||
|
||
这将转换为 JSON ：
|
||
|
||
```json
|
||
{
|
||
"nineteen-eighty-four": {
|
||
"author": "George Orwell",
|
||
"published-at": "1949-06-08T00:00:00.000Z",
|
||
"page-count": 328,
|
||
"description": "A Novel, often published as 1984, is a dystopian novel by English novelist George Orwell.\nIt was published in June 1949 by Secker & Warburg as Orwell's ninth and final book.\n"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 对象列表
|
||
|
||
将序列和嵌套值组合在一起，我们可以创建一个对象列表。
|
||
|
||
```md
|
||
---
|
||
# Let's list books:
|
||
- nineteen-eighty-four:
|
||
author: George Orwell
|
||
published-at: 1949-06-08
|
||
page-count: 328
|
||
description: |
|
||
A Novel, often published as 1984, is a dystopian novel by English novelist George Orwell.
|
||
|
||
- the-hobbit:
|
||
author: J. R. R. Tolkien
|
||
published-at: 1937-09-21
|
||
page-count: 310
|
||
description: |
|
||
The Hobbit, or There and Back Again is a children's fantasy novel by English author J. R. R. Tolkien.
|
||
---
|
||
```
|
||
|
||
## 独特特性
|
||
|
||
以下是一些引起我注意的 __更复杂的功能__ ，它们也使 YAML 与 JSON 区分开来。
|
||
|
||
### 注释
|
||
|
||
你可能已经在我前面的示例中注意到，YAML 允许以 `#` 开头的注释。
|
||
|
||
```md
|
||
---
|
||
# 这是一个非常有用的注释。
|
||
---
|
||
```
|
||
|
||
### 锚点的可重用性
|
||
|
||
节点锚点用于 __标记一个节点__ 以供将来引用，从而允许我们重复使用该节点。
|
||
要标记一个节点，我们使用 `&` 字符，要引用它，我们使用 `*` ：
|
||
|
||
在下面的示例中，我们将定义一个书籍列表并重用作者数据，因此我们只需要定义一次：
|
||
|
||
```md
|
||
---
|
||
# 作者数据：
|
||
author: &gOrwell
|
||
name: George
|
||
last-name: Orwell
|
||
|
||
# 一些书籍：
|
||
books:
|
||
- 1984:
|
||
author: *gOrwell
|
||
- animal-farm:
|
||
author:*gOrwell
|
||
---
|
||
```
|
||
|
||
解析为 JSON 后，上面的代码将如下所示：
|
||
|
||
```json
|
||
{
|
||
"author": {
|
||
"name": "George",
|
||
"last-name": "Orwell"
|
||
},
|
||
"books": [
|
||
{
|
||
"1984": {
|
||
"author": {
|
||
"name": "George",
|
||
"last-name": "Orwell"
|
||
}
|
||
}
|
||
},
|
||
{
|
||
"animal-farm": {
|
||
"author": {
|
||
"name": "George",
|
||
"last-name": "Orwell"
|
||
}
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 带有标签的显式数据类型
|
||
|
||
正如我们在之前的示例中所见，YAML 会自动检测我们值的类型，但我们也可以 __指定所需的类型__ 。
|
||
|
||
我们通过在值前加上 `!!` 类型来指定它。
|
||
|
||
以下是一些示例：
|
||
|
||
```md
|
||
---
|
||
# 以下值应为整数，无论何种情况：
|
||
should-be-int: !!int 3.2
|
||
|
||
# 解析任何值为字符串：
|
||
should-be-string: !!str 30.25
|
||
|
||
# 我需要下一个值为布尔类型：
|
||
should-be-boolean: !!bool yes
|
||
---
|
||
```
|
||
|
||
这将转换为 JSON：
|
||
|
||
```json
|
||
{
|
||
"should-be-int": 3,
|
||
"should-be-string": "30.25",
|
||
"should-be-boolean": true
|
||
}
|
||
```
|