Using YAML

Rhymes with "camel."

All configuration files for Statamic — whether for your site settings, themes you’re using, add-on configuration, or even site-specific variables — is done in YAML. You’ll need to at least know the basics to configure your Statamic site successfully, but don’t worry, it’s pretty easy.

And as with most things, the more you learn about YAML and how Statamic works with it, the more you’ll be able to do, and the more enjoyable your experience will be.

What is YAML?

YAML is a recursive acronym that stands for YAML Ain’t Markup Language. Its aim is to provide a clean, human-readable way to store data that can easily be used elsewhere.

Below is a small sample of YAML.

name: "GOB Bluth"
occupation: Magician
venue: Gothic Castle
siblings:
  - Michael
  - Lindsay
  - Buster
  - Annyong

Even without knowing YAML, you might be able to grasp how data is being stored here. The above code stores four variables: name, occupation, venue, and siblings. The values of the first three variables are simple strings. The last one is a simple list.

How Statamic Uses YAML

Statamic uses YAML in a couple of different ways.

Configuring Things

Statamic uses YAML to configure your main site settings, system-wide features (like routes and vanity URLs), theme-specific settings, and add-on settings. While you probably won’t use them this way, all of the variables set in your site- and theme-settings become available for use as tags within your templates.

Creating Global Variables

You can create any number of additional YAML files within your _config folder to define global variables. These variables also are available for use as tags within your templates.

Page-Specific Variables & Settings

In Statamic, the top of every content file starts with a block of YAML. In this block (called front matter), you can define page-specific variables that can be used as tags within your templates.

Defining Fieldsets for the Control Panel

You can create fieldsets for use in Statamic’s Control Panel so that it knows what fields each piece of content should contain, and can create an interface to let you add and edit content on the fly.

Learn More About YAML

Even if you don’t learn YAML, this guide will try to walk you through things as best it can, but we recommend that you learn YAML, at least a little bit. It’s good for you, and you’ll be able to understand why things work, rather than just copying and pasting from our examples. In turn, you’ll be able to do a lot more with Statamic, and you’ll have a lot more fun.

Here are some helpful links on YAML:

• YAML: The Official Spec is official, but not the most exciting read.
• Wikipedia’s article on YAML is surprisingly great.