--- title: How to Use Frontmatter createTime: 2025/10/09 09:19:36 permalink: /en/article/ecxnxxd0/ --- ::: info Note This article translates parts of [Introduction to YAML](https://dev.to/paulasantamaria/introduction-to-yaml-125f). It provides a basic explanation of how to use frontmatter in markdown files. If you have a good foundation in English reading, to avoid potential content distortion from translation, it is recommended that you read the original article. Original article: . ::: ## Introduction YAML is a data serialization language, commonly used for configuration files, such as the [Open API Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v2.0/yaml/api-with-examples.yaml) or [CI/CD pipelines](https://docs.gitlab.com/ee/ci/yaml/). ::: note Fun Fact! 🤓 According to the [YAML 1.0 Specification Document (2001-05-26)](https://yaml.org/spec/history/2001-05-26.html), the acronym "YAML" stood for "Yet Another Markup Language".However, it was later changed to the recursive acronym "YAML Ain't Markup Language" in the [2002-04-07 specification](https://yaml.org/spec/history/2002-04-07.html). ::: As stated in the latest specification, __YAML__ is designed to be __human-friendly for handling data__ and achieves "unique cleanliness" by __minimizing the use of structural characters__, allowing data to be displayed in a natural and meaningful way. The latest specification also states that YAML _1.2 is officially a superset of JSON_, meaning most JSON documents can be parsed as YAML. YAML makes it easy to inspect data structures by using indentation-based scoping (similar to Python). ::: note Another Fun Fact! 🤓 DEV.to articles use YAML to define custom variables like title, description, tags, etc. ::: ## Basic Syntax A YAML document is essentially a __collection of key-value pairs__, where values can be as simple as a string or as complex as a tree. Here are some notes on YAML syntax: - __Indentation is used to denote structure__. Tabs are not allowed. The number of spaces doesn't matter as long as child nodes are indented more than their parent nodes. - UTF-8, UTF-16, and UTF-32 encodings are permitted. ### Strings ```md --- # Strings do not require quotes: title: Introduction to YAML # But you can still use them: title-w-quotes: 'Introduction to YAML' # Multi-line strings start with | execute: | npm ci npm build npm test --- ``` The above code converts to JSON as: ```json { "title": "Introduction to YAML", "title-w-quotes": "Introduction to YAML", "execute": "npm ci\nnpm build\nnpm test\n" } ``` ### Numbers ```md --- # Integer: age: 29 # Float: price: 15.99 # Scientific notation: population: 2.89e+6 --- ``` The above code converts to JSON as: ```json { "age": 29, "price": 15.99, "population": 2890000 } ``` ### Booleans ```md --- # Booleans can be represented in different ways: published: false published: False published: FALSE --- ``` All of the above will convert to JSON as follows: ```json { "published": false } ``` ### Null Values ```md --- # Null values can be represented by not setting a value: null-value: # Or more explicitly: null-value: null null-value: NULL null-value: Null --- ``` All of the above will convert to JSON as follows: ```json { "null-value": null } ``` ### Dates and Timestamps Dates can be used in ISO format as shown below: ```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 Sequences allow us to define lists in YAML: ```md --- # Numbered list using hyphens: numbers: - one - two - three # Inline version: numbers: [ one, two, three ] --- ``` Both sequences above will parse to JSON as follows: ```json { "numbers": [ "one", "two", "three" ] } ``` ### Nested Values We can use all the types mentioned above to create objects with nested values, as shown below: ```md --- # Data for the novel Nineteen Eighty-Four. 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. --- ``` This converts to JSON as: ```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" } } ``` ### Lists of Objects Combining sequences and nested values, we can create a list of objects. ```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. --- ``` ## Unique Features Here are some __more complex features__ that caught my attention, which also distinguish YAML from JSON. ### Comments As you may have noticed in my previous examples, YAML allows comments starting with `#`. ```md --- # This is a very useful comment. --- ``` ### Reusability with Anchors Node anchors are used to __mark a node__ for future reference, allowing us to reuse that node. To mark a node, we use the `&` character; to reference it, we use `*`: In the following example, we define a list of books and reuse the author data, so we only need to define it once: ```md --- # Author data: author: &gOrwell name: George last-name: Orwell # Some books: books: - 1984: author: *gOrwell - animal-farm: author: *gOrwell --- ``` When parsed to JSON, the above code will look like this: ```json { "author": { "name": "George", "last-name": "Orwell" }, "books": [ { "1984": { "author": { "name": "George", "last-name": "Orwell" } } }, { "animal-farm": { "author": { "name": "George", "last-name": "Orwell" } } } ] } ``` ### Explicit Data Types with Tags As we saw in previous examples, YAML automatically detects the types of our values, but we can also __specify the desired type__. We specify it by prefixing the value with `!!` followed by the type. Here are some examples: ```md --- # The following value should be an integer, regardless: should-be-int: !!int 3.2 # Parse any value as a string: should-be-string: !!str 30.25 # I need the next value to be a boolean: should-be-boolean: !!bool yes --- ``` This converts to JSON as: ```json { "should-be-int": 3, "should-be-string": "30.25", "should-be-boolean": true } ```