YAML Includes Atoms, Maps, and Lists[1]

HIDDEN[1]

Page contents

What is YAML?

YAML is a configuration language and data-serialization format that can include Atoms, Maps and Lists.[2]

Atoms are the elementary particles of a YAML serialization. An atom is usually either…

  • a boolean (e.g. true or false),

  • a number (e.g. 2 or 2.718281828),

  • or a string (e.g. hello world).

A map is a key-value pair. Here are a couple example YAML maps:

key1: value1
key2: value2

Here is an example of a YAML list:

- item1
- item2
- item3

These data structures can have names, also known as keys. For example:

name1:
  key1: value1
  key2: value2

name2:
  - item1
  - item2
  - item3

Note that name1 is a key whose value is a couple maps and name2 is a key whose value is a three-item list. Naming a collection is a way to turn it into a block or object (with sub-objects) that can be referenced.

YAML syntax tips

In general, you do not need to use quotation marks around YAML strings. Quoting a string is required if it…

  • includes a colon (:), hash (#), greater than (>), or any character that has a special meaning in YAML,

  • looks like a number (decimal, hexadecimal, exponential E or e notation, etc.),

  • or is one of YAML’s reserved boolean words (true, false, no, off, etc.).[3]

 

‼

In YAML:

  • Indentation matters.

  • Tabs are not allowed.[4]

  • Lines that begin with a hash (#) are comments and are ignored.

 

Terminology

An atom is also known as a scalar.

A list is also known as an array, a sequence, a slice, or a vector.

A named collection of maps, for example name1, is also known as an associative array, a dictionary, a dict, a hash table, a hash, a keyed list, a map, a mapping, a named map, a nested map, an object, a record, a struct, or a table.

References

To learn more about YAML, see…

Related pages

The following Infinite Ink pages include YAML settings that can be used in a Hugo config file.

Please edit this page 👍 👎 📝

Endnotes

1. An earlier version of this article was in Infinite Ink’s Hugo Tutorial: Themeless & Gitless Introduction to the Hugo Static Site Generator in the section called “7.2 Configuration and front-matter languages.”
2. I like to think that the AML part of YAML stands for Atoms, Maps, and Lists, but this is not what the YAML acronym really stands for.
3. I learned about the off problem the hard way. Here’s a story about someone who learned about the no problem the hard way: The Norway Problem.
4. Tabs are allowed in some parts of a YAML serialization, but it is safest not to use tabs at all.