Lesson 2: Documents and comments
YAML files have a
.yml file extension.
YAML may exist within other files including Markdown (
The course uses bare documents for most examples because most of the documents encountered in day-to-day work are bare documents.
A bare document excludes three dashes
---which indicates the start of the explicit YAML document.
A bare document also excludes three dots
...which indicates the end of the explicit YAML document.
Front matter in Markdown starts with three dashes
---and ends with three dashes
---at the top of the file.
Avoid explicit documents
Explicit documents may confuse your family, friends, and colleagues. Avoid them when possible.
--- weather: sunny --- # My Heading And my body paragraph text.
--- weather: sunny ...
A comment in YAML starts with an octothorpe
The rest of that line is a comment.
This is a comment in front matter of a Markdown file.
--- # This is a comment title: This is our YAML. --- This is the Markdown content.
This is the same YAML in a bare document:
# This is a comment title: This is our YAML.
Comments can start mid-line too.
title: This is our YAML. # This is a comment
If you want to use the literal
# character you may need to escape it.
You can do that with quotes.
title: "This is our YAML. # This is not a comment"
You'll learn more about how to do that in Lesson 4: Scalars.
There's no equivalent to comments in JSON. Comments are a human-friendly feature of YAML.