Yet Another Markup Language (YAML) is a way to create structured text and data—often used for generating websites and configuration.
What’s the point of YAML
YAML’s simple structure is great work creating ☛ content templates and for making systems of website generation.
When using a system like ☛ Jekyll, YAML can bet used for extra metadata about the document that isn’t part of the main content, that can be used in different places.
A couple examples:
- This tutorial uses YAML, see the source code
- The Markdown & YAML cheat sheet is written in YAML, see the code
Indent with spaces
YAML is really strict about this: indent with 2 spaces only.
YAML is for structuring data and information using systems like objects and arrays from programming languages.
The data of YAML has two main structures:
- objects: like
<dl>elements in HTML, or
- arrays: like
<ul>elements in HTML, or
Objects in YAML are started with a word/term followed by a colon and space. You make up the term so that it suits your data.
We can have as many items in the object as we want:
name: Tyrannosaurus period: Late Cretaceous age: 160
We can even have objects inside other objects, just by starting a new term:
dimensions: width: 3 metres height: 8 metres length: 12 metres weight: 4 tonnes
Arrays are just a big list or collection, each item starting with a dash. They keep their order when output in systems.
likes_to_eat: - Other dinosaurs - Meat - More meat - Not plants
Above you can see that the array is inside an object. But it can be the other way around too, objects inside arrays:
- name: T. rex period: Late Cretaceous Period - name: Stegosaurus period: Late Jurassic Period - name: Velociraptor period: Cretaceous Period
If you have super large text blocks in your YAML, you can use vertical pipes (
|) or greater than symbols (
>) to separate the text out and allow a little more formatting.
The greater than symbol allows you to write your text on multiple lines, knowing that when your YAML is parsed those lines will be collapsed into a single line.
desc: > Tyrannosaurus (/tɨˌrænəˈsɔrəs/ or /taɪˌrænəˈsɔrəs/ ("tyrant lizard", from the Ancient Greek tyrannos (τύραννος), "tyrant", and sauros (σαῦρος), "lizard")) is a genus of coelurosaurian theropod dinosaur. The species Tyrannosaurus rex (rex meaning "king" in Latin), commonly abbreviated to T. rex, is one of the most well-represented of the large theropods.
The vertical pipe allows you to write your text on multiple lines, knowing that those multiple lines will be kept when the YAML is parsed.
poem: | T. rex, T.rex How I love thee
The vertical pipe is really great for embedding code samples in YAML:
code: | <div> <h1>Things</h1> <p>Things....</p> </div>
Sometimes YAML can get confused between content and structure—like for instance when using ampersands. If that’s the case, we can wrap the content in quotes to escape it.
name_meaning: "tyrant & lizard"
Markdown front matter
We use Markdown for structuring our content, but sometimes you want to add more structured data to your Markdown that just the default formatting. This can be accomplished with YAML front matter.
At the top of your Markdown document, you put a series of three double dashes and provide more data between them:
--- name: Venus discoverer: Galileo Galilei discovered: 1610 orbit: 247 days radius: 6051 km tilt: 177° --- *Venus* is the second planet from the Sun, orbiting it every 224.7 Earth days.
This data can then be used in lots of applications, including Jekyll.