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.
go get oneyaml.dev/goRequires Go 1.24+. Run in a Go module.
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 ..
# Public listener port: 80
The full program
config.yaml is in the download:
service: port: 80 host: 'example.org' # leave this as is
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) }
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:
note := "Public listener\nSet by deployment"# Public listener # Set by deployment port: 80
A comment after the value. Replace the SetHeadComment call’s assignment:
err = doc.SetLineComment("/port", note)port: 80 # Public listenerRelated recipes
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.