Helping new non-tech users understand yaml

If you have followed the official documentation or one of the community guides. You should now have a running instance Of HassOS on your Pi.

So now you may want to move into some useful configurations, add-ons and Integrations.

There are no two ways about it to get the very best from HassOS you will need to learn yaml

What is yaml? You can read a very detailed description here:

But to keep things basic for new users it is configuration language. It is how your configuration files are laid out and how ESPhome is configured.

The best way to start out is by using the many examples in the documentation and forums. There are a number of video tutorials on YouTube by many of the active users on these forums.


So lets look at an example and break it down using sensor as the parent. It is important to use two spaces and NOT the tab key.

sensor: #this is the parent 
  - platform: time_date # this is the first child  it sits two spaces back underneath the parent.
    display_options: # in this case the options are listed  directly in line with the first child
      - 'time' # here we have the actual list of the options we want to record.
      - 'date' # note that as these are a subset 'grandchildren if you like' then they sit two spaces behind the fist child
      - 'date_time' #It is also important to note that as there are 6 grandchildren then they must be set using a hyphen.
      - 'time_date' # a space must follow the hyphen.
      - 'time_utc' 
      - 'beat'
  - platform: zoneminder # this is the second child of the parent note again the two spaces, the hyphen and the space
    monitored_conditions: week #In this case the child only has one grandchild so it can be shown with a colon and a following space
  - platform: version # This child has no grandchildren so can be written like this.

Observe that each of the parents children sit the two spaces back, with the hyphen and the space. This is because they share the same first name.

There are other ways to write this in yaml but IMHO this is the simplest and should get you started.

Now lets have a look at an example from ESPHome. There is an excellent resource for this add-on that shows the supported devices along with examples

esphome: #this is a parent
  name: comms #this a child of that parent
  platform: ESP8266 #this is also a child of the parent
  board: d1_mini # in this case as the first name of the child is different so we do not need the hyphen

wifi: # this is a parent
  ssid: !secret mywifi # this is a child of the parent wifi
  password: !secret mywifipw # this is a child of the parent wifi again with a different first name

  ap: # this is a child of the parent wifi note the two spaces
    ssid: "Comms Fallback Hotspot" # this is a child of ap and a grandchild to wifi
    password: "9TUwdQty3jba" # again the grandchild of wifi with a different first name

captive_portal: # A childless parent

# Enable logging
logger: # A childless parent

# Enable Home Assistant API
api: # a parent with one child
  password: !secret apipw

ota: # a parent with one child
  password: !secret otapw

sensor: # a parent with one child but may have another later so two spaces one hyphen and one space
  - platform: dht # child
    model: AM2302 #child option
    pin: D7 #child option
    temperature: #child option with a grandchild
      name: "Case Temp" # only child of the option temperature
    humidity: #child option with a grandchild
      name: "Case Humidity" # only child of the option humidity
    update_interval: 20s #child option

Hopefully, this will help new non-techie users to understand a little more about yaml.


This is a good yaml primer too:


How about a guide for non-tech users on how to avoid using yaml? After all, there’s probably a reason why they’re non-tech. :smile:

Easy. Uninstall home assistant and go play minecraft.


Feel free to write it. My late father used to say if you can’t help then don’t hinder!
I am sure you want to help?

1 Like

I think you can easily run home-assistant without yaml now. You miss out on a lot of functionality, but using pretty standard commonly available hardware you could do it.

Of course the bits you miss out are the fun bits.

Agreed but we need a transition. So to start from the basics is a good thing, It also helps with troubleshooting.

And it doesn’t help that the YAML used in the UI is sometimes different from the YAML used in a text file - which makes it even harder and more confusing for non-programmers and leads to them fearing YAML/actively avoiding use of it.

Everything is easy when you know how, unfortunately many here that know have forgotten how hard that knowledge was to acquire in the first place.

That is a fair comment.

But practice, practice, practice. And ask on the forum. And use yaml checkers on the internet.

But please, never post a bloody photo of a text file, whether it a yaml file or a log file or whatever. Copy and paste was invented before most users 'round here were born.

All I wanted to do is provide a simplified method of understanding YAML. @Tromperie thanks for the spelling correction. Thunder fingers it happens a lot when you have hands like shovels! :laughing:

It is tough to learn any language or but persistence and practice are the only answers. There simply is no easy path and for the record there should not be. You must understand your actions because your configuration is your responsibility and security has no easy path.

Heh, I’m a techie user. Even so, I just learned that YAML wasn’t something the HA devs made up in their garage – my first guess. I admit when I started HA I took one look at YAML and turned to Node-Red. But now that I know YAML is a thing and I can find documentation out on the internet regarding its syntax, I’m motivated to actually learn it.

I suspect I’ll always prefer Node-Red. But YAML is inescapable in Home Assistant and it’d be good if I had some clue how it worked.

I wish this guide had been more clear on those cursed hyphens… they seem to be used semi-randomly. I’m looking forward to finding some solid information on when you do and don’t need a hyphen.