Recursive AI

Add a comment to a YAML file in Go

oneyaml-go is a free, open-source YAML library for Go from Recursive AI. MIT or Apache-2.0, no dependencies.

Call SetHeadComment with the key’s path and the note. Separate keys with slashes: /service/port selects a nested key, and /items/0 selects the first list item.

Terminal
go get oneyaml.dev/go

Requires Go 1.24+. Run in a Go module.

GO
package main
 
import (
	"fmt"
	"oneyaml.dev/go"
)
 
func main() {
	input := "port: 80\n"
	doc, err := oneyaml.Parse([]byte(input))
	if err != nil {
		panic(err)
	}
	note := "Public listener"
	err = doc.SetHeadComment("/port", note)
	if err != nil {
		panic(err)
	}
	fmt.Print(doc)
}

Unzip the example, then go run ..

Text
# Public listener
port: 80

The full program

config.yaml is in the download:

YAML
service:
  port: 80
  host: 'example.org' # leave this as is
GO
package main
 
import (
	"fmt"
	"oneyaml.dev/go"
	"os"
)
 
func main() {
	input, err := os.ReadFile("config.yaml")
	if err != nil {
		panic(err)
	}
	doc, err := oneyaml.Parse(input)
	if err != nil {
		panic(err)
	}
	note := "Public listener"
	err = doc.SetHeadComment("/service/port", note)
	if err != nil {
		panic(err)
	}
	err = os.WriteFile("updated.yaml", doc.Bytes(), 0644)
	if err != nil {
		panic(err)
	}
	fmt.Print(doc)
}
Text
service:
  # Public listener
  port: 80
  host: 'example.org' # leave this as is

The download reads config.yaml, adds the note above /service/port, and writes updated.yaml without touching the input. SetHeadComment returns ErrUnsupportedEdit for an entry inside a brace-delimited mapping such as {port: 80}.

Variations

Two lines above the key. Replace the note assignment:

GO
note := "Public listener\nSet by deployment"
Text
# Public listener
# Set by deployment
port: 80

A comment after the value. Replace the SetHeadComment call’s assignment:

GO
err = doc.SetLineComment("/port", note)
Text
port: 80 # Public listener

The short answer

Call SetHeadComment with a pointer to the entry and the text to put above it. Pass the text without a # and the library will add the marker and match the key’s indentation. Save doc.Bytes() only after the edit succeeds.

How do I insert comments in a YAML file?

A YAML comment can go on its own line before an entry, or after the entry’s value. If you’re adding a note for someone editing that setting later, a line above it gives you room to explain the reason for the setting. For a short note such as where a value came from, an inline comment uses less space. In both cases the application reading the YAML gets the same value. A # within a quoted string isn’t a comment marker; see the YAML comment syntax.

With oneyaml-go, a pointer like /service/port selects the target entry in the document, so you don’t have to find a line by searching for port:. That matters when the same key appears under several parents. SetHeadComment replaces the comment lines directly above the target; it doesn’t append to them. Passing an empty string removes those lines. Use SetLineComment instead to change the inline comment without replacing the one above.

How do I add a multiline comment in YAML?

YAML has no start and end markers that turn a group of lines into a block comment. Each line of the note needs its own #. Pass one Go string with \n between its lines to SetHeadComment, as in the two-line variation. The setter also turns a blank line inside the text into a line containing just #, so the note can contain separate paragraphs. SetLineComment takes only a single line.

Indentation matters when you want a note to sit next to a nested key. Let the document edit add the indentation rather than including spaces for it in the text. If the first key of a sequence item shares a line with its dash, the setter can’t put a head comment above that key; choose the item or use a place in the file that can hold the note. The editing guide lists positions where comment edits are refused.

All oneyaml Go recipes