H YAML

YAML is a way to write nested data structures in plain text that is often used to specify configuration options for software. The acronym stands for “YAML Ain’t Markup Language,” but that’s misleading: YAML doesn’t use tags like HTML, but can still be quite fussy about what is allowed to appear where.

Throughout this book we use YAML to configure our plotting script (Chapter 10), continuous integration with Travis CI (Section 11.8), software environment with conda (Section 13.2.1), and a documentation website with Read the Docs (Section 14.6.3). While you don’t need to be an expert in YAML to complete tasks like these, this appendix outlines some basics that can help make things easier.

A simple YAML file has one key-value pair on each line with a colon separating the key from the value:

project-name: planet earth
purpose: science fair
moons: 1

Here, the keys are "project-name", "purpose", and "moons", and the values are "planet earth", "science fair", and (hopefully) the number 1, since most YAML implementations try to guess the type of data.

If we want to create a list of values without keys, we can write it either using square brackets (like a Python array) or dashed items (like a Markdown list), so:

rotation-time: ["1 year", "12 months", "365.25 days"]

and:

rotation-time:
    - 1 year
    - 12 months
    - 365.25 days

are equivalent. (The indentation isn’t absolutely required in this case, but helps make the intention clear.) If we want to write entire paragraphs, we can use a marker to show that a value spans multiple lines:

feedback: |
    Neat molten core concept.
    Too much water.
    Could have used more imaginative ending.

We can also add comments using # just as we do in many programming languages.

YAML is easy to understand when used this way, but it starts to get tricky as soon as sub-lists and sub-keys appear. For example, this is part of the YAML configuration file for formatting this book:

bookdown::gitbook:
  highlight: tango
  config:
    download: ["pdf", "epub"]
    toc:
      collapse: section
      before: |
        <li><a href="./">Merely Useful</a></li>
    sharing: no

It corresponds to the following Python data structure:

{
  'bookdown::gitbook': {
    'highlight': 'tango',
    'config': {
      'download': [
        'pdf',
        'epub'
      ],
      'toc': {
        'collapse': 'section',
        'before': '<li><a href="./">Merely Useful</a></li>\n'
      }
      'sharing': False
    }
  }
}