From 2175f9ec7ccea211b0a2dbf64e7ec915cfccbf26 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Sun, 10 Dec 2023 21:12:33 +0100
Subject: [PATCH] docs: add levels to bake file target.annotations

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
(cherry picked from commit c6535e967596414f83d627e89439682b1f77b68a)
---
 docs/bake-reference.md | 23 +++++++++++++++++++----
 1 file changed, 19 insertions(+), 4 deletions(-)

diff --git a/docs/bake-reference.md b/docs/bake-reference.md
index 2c113f8a..50cf90f9 100644
--- a/docs/bake-reference.md
+++ b/docs/bake-reference.md
@@ -274,13 +274,13 @@ target "db" {
 
 ### `target.annotations`
 
-The `annotations` attribute is a shortcut to allow you to easily set a list of
-annotations on the target.
+The `annotations` attribute lets you add annotations to images built with bake.
+The key takes a list of annotations, in the format of `KEY=VALUE`.
 
 ```hcl
 target "default" {
   output = ["type=image,name=foo"]
-  annotations = ["key=value"]
+  annotations = ["org.opencontainers.image.authors=dvdksn"]
 }
 ```
 
@@ -288,10 +288,25 @@ is the same as
 
 ```hcl
 target "default" {
-  output = ["type=image,name=foo,annotation.key=value"]
+  output = ["type=image,name=foo,annotation.org.opencontainers.image.authors=dvdksn"]
 }
 ```
 
+By default, the annotation is added to image manifests. You can configure the
+level of the annotations by adding a prefix to the annotation, containing a
+comma-separated list of all the levels that you want to annotate. The following
+example adds annotations to both the image index and manifests.
+
+```hcl
+target "default" {
+  output = ["type=image,name=foo"]
+  annotations = ["index,manifest:org.opencontainers.image.authors=dvdksn"]
+}
+```
+
+Read about the supported levels in
+[Specifying annotation levels](https://docs.docker.com/build/building/annotations/#specifying-annotation-levels).
+
 ### `target.attest`
 
 The `attest` attribute lets you apply [build attestations][attestations] to the target.