---
title: "Add a comment to a YAML file in Go"
url: https://recursiveai.org/oneyaml/go/cookbook/add-comment-to-yaml/
description: "Add a comment above a YAML key in Go without reserializing the mapping. See how to add multiple comment lines or an inline comment."
version: "1.0.0"
---

# 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.

[pkg.go.dev](https://pkg.go.dev/oneyaml.dev/go) · [GitHub](https://github.com/recursive-ai-oss/oneyaml-go) · [Docs](https://recursiveai.org/oneyaml/go/docs/) · [Download example (.zip)](https://recursiveai.org/oneyaml/go/cookbook/add-comment-to-yaml/add-comment-to-yaml.zip)

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.

```shell
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](https://recursiveai.org/oneyaml/go/cookbook/add-comment-to-yaml/add-comment-to-yaml.zip), 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
```

## Related recipes

- [Edit a YAML file and keep its comments](https://recursiveai.org/oneyaml/go/cookbook/edit-yaml-keep-comments/)
- [Rename a YAML key without losing comments](https://recursiveai.org/oneyaml/go/cookbook/rename-yaml-key-keep-comments/)

## 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](https://yaml.org/spec/1.2.2/#66-comments).

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](https://recursiveai.org/oneyaml/go/docs/editing/#comments) lists positions where comment edits are refused.
