YAML stands for "YAML Ain't Markup Language" and it is used extensively in Grav for its configuration files, blueprints, and also in page settings.
YAML is built from the ground up to be simple to use. At its core, a YAML file is used to describe data. One of the benefits of using YAML is that the information in a single YAML file can be easily translated to multiple language types.
Basically, the data you enter in a YAML file is used in conjunction with a library to create the pages you see within Grav.
There are some rules that YAML has in place to avoid issues related to ambiguity in relation to various languages and editing programs. These rules make it possible for a single YAML file to be interpreted consistently, regardless of which application and/or library is being used to interpret it.
.yamlwhenever possible in Grav.
Scalars are a pretty basic concept. They are the strings and numbers that make up the data on the page. A scalar could be a boolean property, like
true, integer (number) such as
5, or a string of text, like a sentence or the title of your website.
Scalars are often called variables in programming. If you were making a list of types of animals, they would be the names given to those animals.
Most scalars are unquoted, but if you are typing a string that uses punctuation and other elements that can be confused with YAML syntax (dashes, colons, etc.) you may want to quote this data using single
' or double
" quotation marks. Double quotation marks allow you to use escapings to represent ASCII and Unicode characters.
integer: 25 string: "25" float: 25.0 boolean: true
~ and dates have special meaning in YAML. Please quote them if you do not want to use them as a boolean, null or datetime type. Same is true with version numbers, they should be quoted to separate them from float values.
Here is a simple sequence you might find in Grav. It is a basic list with each item in the list placed in its own line with an opening dash.
- Cat - Dog - Goldfish
This sequence places each item in the list at the same level. If you want to create a nested sequence with items and sub-items, you can do so by placing a single space before each dash in the sub-items. YAML uses spaces, NOT tabs, for indentation. You can see an example of this below.
- - Cat - Dog - Goldfish - - Python - Lion - Tiger
If you wish to nest your sequences even deeper, you just need to add more levels.
- - - Cat - Dog - Goldfish
Sequences can be added to other data structure types, such as mappings or scalars.
Mapping gives you the ability to list keys with values. This is useful in cases where you are assigning a name or a property to a specific element.
This example maps the value of
pets to the
animal key. When used in conjunction with a sequence, you can see that you are starting to build a list of
pets. In the following example, the dash used to label each item counts as indentation, making the line items the child and the mapping line
pets the parent.
pets: - Cat - Dog - Goldfish
For more information about YAML, including detailed documentation about how it works, check out the resources linked below.
Found errors? Think you can improve this documentation? Simply click the Edit link at the top of the page, and then the icon on Github to make your changes.