From a494e9ccc472e1a2b9c4956de5bd15f3e9276ba3 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Sun, 10 Dec 2023 16:20:12 +0100
Subject: [PATCH] docs: imagetools create --annotation

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
(cherry picked from commit a4c392f4dbeaa1f01622dc6f811fe1566d68753e)
---
 docs/reference/buildx_imagetools_create.md | 30 +++++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

diff --git a/docs/reference/buildx_imagetools_create.md b/docs/reference/buildx_imagetools_create.md
index e714cd9c..b55c8374 100644
--- a/docs/reference/buildx_imagetools_create.md
+++ b/docs/reference/buildx_imagetools_create.md
@@ -11,7 +11,7 @@ Create a new image based on source images
 
 | Name                             | Type          | Default | Description                                                                              |
 |:---------------------------------|:--------------|:--------|:-----------------------------------------------------------------------------------------|
-| `--annotation`                   | `stringArray` |         | Add annotation to the image                                                              |
+| [`--annotation`](#annotation)    | `stringArray` |         | Add annotation to the image                                                              |
 | [`--append`](#append)            |               |         | Append to existing manifest                                                              |
 | [`--builder`](#builder)          | `string`      |         | Override the configured builder instance                                                 |
 | [`--dry-run`](#dry-run)          |               |         | Show final image instead of pushing                                                      |
@@ -31,6 +31,34 @@ specified, create performs a carbon copy.
 
 ## Examples
 
+### <a name="annotation"></a> Add annotations to an image (--annotation)
+
+The `--annotation` flag lets you add annotations the image index, manifest,
+and descriptors when creating a new image.
+
+The following command creates a `foo/bar:latest` image with the
+`org.opencontainers.image.authors` annotation on the image index.
+
+```console
+$ docker buildx imagetools create \
+  --annotation "index:org.opencontainers.image.authors=dvdksn" \
+  --tag foo/bar:latest \
+  foo/bar:alpha foo/bar:beta foo/bar:gamma
+```
+
+> **Note**
+>
+> The `imagetools create` command supports adding annotations to the image
+> index and descriptor, using the following type prefixes:
+>
+> - `index:`
+> - `manifest-descriptor:`
+>
+> It doesn't support annotating manifests or OCI layouts.
+
+For more information about annotations, see
+[Annotations](https://docs.docker.com/build/building/annotations/).
+
 ### <a name="append"></a> Append new sources to an existing manifest list (--append)
 
 Use the `--append` flag to append the new sources to an existing manifest list