Most of OctoPrint’s configuration is done under the hood through YAML files,
which is why it makes sense to shed some light on the basics of this data serialization format.

YAML is a text based format which excels at representing the most common of data structures in an easy and very human
readable way, which is why it was chosen for OctoPrint’s configuration files. A text editor is all you need in order
to write YAML configuration files.

You will probably only come across the three most basic types of data within OctoPrint’s YAML files: scalars
(such as strings, integers, …), lists and associated arrays (aka key-value-pairs, aka maps, aka dictionaries).

Scalars are the most basic of all data types and are simple string, integer, float or boolean values.

For most scalars you don’t need any quotes at all, but if you need to define some piece of data which contains characters
that could be mistaken with YAML syntax you need to quote it in either double " or single ' quotes for the
YAML file to stay valid. As simple rule of thumb, if your data contains any of these characters :-{}[]!#|>&%@ better
quote it. Also quote it if you want a string but it could be mistaken for a valid number (integer or float) or if
it consists only of “Yes”, “No”, “yes”, “no”, “true” or “false”, which would be converted to a boolean without quotes.

In double quoted strings if you need to include a literal double quote in your string you can escape it by prefixing
it with a backslash \ (which you can in turn escape by itself). In single quoted strings the single quote character
can be escaped by prefixing it with another single quote, basically doubling it. Backslashes in single quoted strings
do not need to be escaped.

Quoted strings can also span across multiple lines, just indent the following lines. Note that you’ll need to add a
completely empty line in order for force a line break, the data will not be actually wrapped across multiple lines
just because you spread its representation across multiple lines.

a string"some quoted string with a:colon and a { bracket and a quote \" and a backslash \\ - phew"'somesinglequotedstringwithasinglequote''andabackslash\-yay'"andamultilinestring-justbecausewecanwe'llmakeitspanacrossnottwobutfourYAMLlines!Includingthisparagraph.Butinfactitwillonlybetwolines:)""23""42.3""Yes""No""true""false"yes and notrue or false

In this example we have a dictionary on the top most “layer” which has three keys, general, specific and
the_end.

general in turn is a dictionary with the keys some_setting (a string), a_list (a list with four items,
a string, a float, an int and a boolean), some_flag (a boolean) and quoted_string (a – you guessed it – string).

specific is also a dictionary, with keys setting1 (a string) and setting2, a dictionary with two keys, one
a string and the other again a list.

Don’t get confused by the list “dividing” one part of the dictionary under general from the other – your mind is
just playing a trick on you due to the list’s dashes - being on the same levels as the dictionary keys. You could
also just add two more spaces to your indentation and write that part like this, which makes the structure a bit
clearer (whitespace again made visible to help track indentation):

Just make sure you follow a consistent way of indenting your files – YAML is not as strict as Python when it comes to
differing indentation variants within the same file (as long as it’s still valid), but consistency will help you as
a lot as a human. Ideally you’ll use a text editor which highlights white space characters for you (most editors can
be configured this way), this will help tremendously when editing whitespace sensitive syntax such as YAML.