Editing YAML Configuration Files

Many Minecraft plugins store their configuration settings within text files in the YAML format. These files have the .yml or .yaml file extension. This article covers how you can edit these files and ensure that they are in the correct format. An incorrectly formatted YAML file can cause a plugin to fail to load or behave incorrectly. They can even prevent a server from starting.

What is YAML?

YAML is a way of storing data in a way that is easy for humans to read. It is designed to be as simple to use as possible. Here's an example of what some YAML looks like:

# I am a comment line
string: This is a text string #Comments can appear in line too
number: 15
array type 1: [string1,string2,"string3: With a special character!"]
array type 2:
  - string1
  - string2
  - "Some special characters like double-quotes \" need to be escaped"
associative array type 1:
  key1: value1
  key2: value2
  key3: [can, also, be, an, array]
  key4:
	key4-1: "You can nest associative arrays!"
associative array type 2: {key1: value1, key2: value2}
folded text: >
  These separate
  lines will be merged
  into one

  A blank line starts
  a new paragraph
literal text: |
  The linebreaks for
  this text will be preserved.
  The indent on the first line
  will be removed from each line
	extra indentation will be preserved

Another data format that is commonly used for humans to be able to read is JSON. JSON isn't the easiest for humans to be able to read due to it using brackets to indicate nested structures rather than indentation. YAML is a very easy format to break so you have to be very aware when editing configuration files that use it. Below we will discuss the basic rules for YAML so that you can make sure to keep your server running as smoothly as possible.

Basic YAML Rules

You can find more rules and examples by looking at: The YAML Specification
The YAML specification goes very in depth for how you can use YAML, but the rules listed below are almost always enough for configuring plugins on your Minecraft server.

• Whitespace indentation is used to denote structure. However, the Tab character must not be used. You can indent by any number of spaces but most plugins use YAML formatted with 2 space characters for each indentation "level"
• Comments are denoted by a number or hashtag symbol: #
  Comments can appear on a line of their own or at the end of any line. There must be whitespace between the data and the comment
• List items are denoted by a leading hyphen: -
  List items may also be enclosed in square brackets [ ] and separated by a comma and a space ,
• Dictionary items are represented using a key and its value separated by a colon and a space key: value . Two items on the same indentation level cannot have the same key value.
  They may also be enclosed inside curly braces { } and separated by a comma and a space , .
• The text used for a key or a value does not need to be inside single quotes ' or double quotes " . However you can use them if you want to include leading or trailing whitespace
  You will also want to use double quotes if you want a string to contain some of YAML's special characters. YAML's special characters consist of different characters depending on where you are in the data structure.

Finding YAML Config Files in The Multicraft Control Panel

The StickyPiston Multicraft Control Panel has been told to look for configuration files on your server in the plugins/ folder and all sub folders. We have also told it to search in specific special cases where the config files are stored in deeper sub folders or in other locations.
You can view a list of all the config files found by the control panel by following the below steps:

1. Log into Multicraft
2. In the Files section of the side menu on the left, select Config Files.
   
3. You can filter the files by using the search boxes above each column, if you want to find a configuration for a specific plugin, you can search the plugin name in the Description column of the config file list.

Editing Config Files

We have replaced the default text editor with CodeMirror. This provides some useful extra features to make it easier to edit configs:

• Code Highlighting
• Auto Indentation
• Line Numbering
• Full Screen Mode (F11)
• Bracket and Tag Matching
• Search (Ctrl+F)

Your code will also be automatically parsed and checked for errors as you type. If the code is valid then it will display in a tree structure below the editor. If there is an error, it will be displayed instead. The parser does not catch all errors, we suggest that you also use the YAMLlint or Online YAML Parser tool. See Checking Your YAML Code below

When you have finished editing the file, click the Save button below the editor.

Downloading to your Computer and Editing the File

You can download the config file using FTP. Check out our guide: How to: Use FTP to Upload and Download Files

We recommend using a text editor that supports code highlighting. Notepad++ is free and can be downloaded here: Notepad++ Download

Configuring Notepad++ Tab Settings for YAML Files

By default pressing the Tab key in a YAML file will insert a tab character. However, most YAML files used by Minecraft mods and plugins use a double space to indent the text. Since YAML files use indentation to denote structure, it's a good idea to force Notepad++ to input 2 spaces instead of a tab when the tab key is pressed. This will help prevent errors.

1. Go to Settings then Preferences
2. In the list on the left highlight Tab Settings
3. Scroll down the list on the right, find and highlight yaml
4. Uncheck the Use default value box
5. Check the Replace by space box
6. Click on the number next to Tab size:
7. In the box that appears, change the number to 2 and press enter
8. Click the Close button

Now when you open a YAML file, the indents will be correctly displayed and when you press tab it will insert two spaces.

Checking Your YAML Code

Most text editors will not check that your code is valid. You can use an external tool like: YAML linter or Appspot YAML Parser to check your code.

Copy the text from your editor and paste it into the YAMLlint website and click the Go button. It will then tell you if there are any errors and the line number that it detected it on. YAMLlint will restructure your YAML code and remove comments. Fix the code in your editor and then paste it into YAMLlint to try again. The Appspot parser will check your code for errors as you type it.

Common YAML Parser Errors

Duplicate Key

duplicated mapping key at line 3, column 27:
      child key: duplicate key
                              ^

You have placed two items with the same key inside the same item at the same level

parent key:
  child key: first appearance
  child key: duplicate key

Remove one of the duplicates

Bad Indentation

bad indentation of a mapping entry at line 3, column 2:
     Team B: 4
     ^

A line’s indentation does not match the current indentation level

scores:
  Team A: 10
 Team B: 4
  Team C: 7

Correct the indentation of the line so that it matches the ones above

Missing a Space Between a 'key: value' pair

On the first item in a Dictionary

bad indentation of a mapping entry at line 3, column 9:
      Team B: 4
            ^

Note that it throws a bad indentation error on the semi-colon of the line after

scores:
  Team A:10
  Team B: 4
  Team C: 7

On an item in the middle of a Dictionary

can not read a block mapping entry; a multiline key may not be an implicit key at line 4, column 9:
      Team C: 7
            ^

Note that it throws a can not read implicit mapping pair on the semi-colon of the line after

scores:
  Team A: 10
  Team B:4
  Team C: 7

On the last item in a Dictionary

can not read an implicit mapping pair; a colon is missed at line 4, column 11:
      Team C:7
              ^

This one gives the error on the offending line

scores:
  Team A: 10
  Team B: 4
  Team C:7

Tab Character in the Code

The CodeMirror YAML parser will not give you this error. Different YAML parsers will return errors along the lines of:

while scanning for the next token
found character '\t' that cannot start any token
  in "<unicode string>", line 6, column 1:
        - value
    ^

found character '\t' that cannot start any token in "<unicode string>", line 6, character 1

found character that cannot start any token while scanning for the next token at line 6 column 1

found a tab character that violate intendation

StickyPiston Support

If you have questions about this guide or our Minecraft services, open a support ticket and our dedicated team will be in touch.

Open Support Ticket