Preserve YAML comments in GUI automation editor

[bartoszperko]

Describe the feature

When editing automations in the Home Assistant UI, any inline YAML comments (lines starting with #) are removed after saving. This often happens in the variables: section or inside action sequences.

It would be extremely helpful if the GUI could preserve YAML comments, or allow annotations per field/step to retain context, especially when using Jinja templating or complex logic.

Use cases

• Documenting what individual variables are used for (e.g., "brightness percent for night light").
• Explaining choose: branches or template conditions.
• Helping others (or future me) understand why something is done a certain way in automations.
• Avoiding external documentation for internal logic.

Current workarounds

• I use only description: field as a pseudo-comment block.
• I edit YAML automations only via automations.yaml file and avoid GUI completely.
• I avoid using GUI just to preserve inline notes, which is not ideal.

Anything else?

Many users report confusion when comments vanish after a single edit in the GUI.
Even preserving them only in variables: or action: blocks would already help a lot.

[frenck]

Unfortunately, this is not an Home Assistant limitation, but a limitation by the Python library available and used: pyyaml.

We've seen this feature request many times before, but the root cause and solution is unfortunately not Home Assistant.

../Frenck

[BBE-FR]

This is a limitation with the comment based on "#" character. But couldn't we find and/or document a workaround to have a new yaml entry or "object" that would cover the comments function and be kept in the interface?

[frenck]

It is not just the # character. For example, styling, spacing, anchors & references.
This is not limited to just comments.

[BBE-FR]

Fully agree. But the fact that YAML to JSON conversion is not perfect does not remove the need to try to adress the functionality to write and store free text in the GUI.

For me these are 2 linked and separated subject:

• One is the limitation of the current tool and architecture that you describe (and which is probably a dead end street with no workaround).
• the other could be addressing the need with another functionality (see answer below).

[frenck]

You are diverging from the original OP.

[BBE-FR]

Really? Could we preserve comment without a proper comment object ?

[edit] I think you are right. I deleted my answer below and proposed another FR for comments in UI there: https://github.com/orgs/home-assistant/discussions/541